docs: document current documentation structure and improvement opportunities #453
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
Welcome @dhruv1955! It looks like this is your first PR to volcano-sh/website 🎉 |
Summary of ChangesHello @dhruv1955, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a comprehensive analysis document for the Volcano project's website documentation. The document meticulously outlines the current documentation structure, pinpoints existing pain points related to discoverability, maintainability, and contributor experience, and proposes a strategic roadmap of incremental, low-risk improvements. The aim is to enhance the overall quality and usability of the documentation without immediate changes to content or underlying infrastructure, serving as a foundational reference for future documentation initiatives. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
volcano-sh-bot
added
the
size/L
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This is an excellent and thorough analysis of the current state of Volcano's documentation. The document is well-structured, clearly identifies existing pain points, and proposes a set of concrete, actionable improvements. This provides a great foundation for future work on improving the documentation's maintainability and user experience. I have one suggestion to improve the structure of the document itself.
| **Documentation Templates**: Create standardized front matter templates for different documentation types (concepts, features, integrations, tutorials) to ensure consistency. | ||
|
|
||
| **Version Management Strategy**: | ||
| - Document a clear policy for which versions to maintain | ||
| - Create a deprecation notice template for older versions | ||
| - Establish a process for archiving very old versions | ||
|
|
||
| **Menu Configuration Simplification**: | ||
| - Consider using Hugo's menu configuration features to reduce duplication | ||
| - Document the menu structure clearly for contributors | ||
| - Create helper scripts or documentation for adding new pages | ||
|
|
||
| **Consolidate Documentation Locations**: | ||
| - Evaluate the purpose of `website/doc/` directory | ||
| - Migrate or link content to avoid duplication | ||
| - Document the canonical location for different types of content | ||
|
|
||
| **Documentation Maintenance Guide**: | ||
| - Create a `MAINTAINING.md` guide for documentation maintainers | ||
| - Document the versioning strategy | ||
| - Provide examples of common documentation tasks | ||
|
|
||
| ### 5.4 Improvements Without Changing Site Generator | ||
|
|
||
| **Enhanced Navigation**: | ||
| - Add a "Documentation" link to the main navigation menu | ||
| - Create a documentation landing page with clear sections for different audiences | ||
| - Add breadcrumb navigation for better context | ||
| - Implement a "version selector" widget on documentation pages | ||
|
|
||
| **Search and Discovery**: | ||
| - Ensure Hugo's built-in search is properly configured | ||
| - Add a "Related Documentation" section to pages | ||
| - Create topic-based index pages (e.g., "All GPU-related documentation") | ||
|
|
||
| **Content Organization**: | ||
| - Add "Last Updated" dates prominently (already present, ensure consistency) | ||
| - Add "Applicable Versions" metadata to pages | ||
| - Create "What's New" or "Recent Changes" documentation section | ||
|
|
||
| **Contributor Experience**: | ||
| - Create a `docs/CONTRIBUTING.md` with documentation contribution guidelines | ||
| - Add examples of well-structured documentation pages | ||
| - Document the review process for documentation PRs |
There was a problem hiding this comment.
For better document structure and readability, consider using level 4 markdown headings (####) for the sub-topics in sections 5.3 and 5.4 instead of bolded text. This will create a clearer hierarchy and may also be reflected in the table of contents, making navigation easier.
For example:
### 5.3 Ideas to Make Documentation Easier to Maintain
#### Documentation Templates
Create standardized front matter templates for different documentation types (concepts, features, integrations, tutorials) to ensure consistency.
#### Version Management Strategy
- Document a clear policy for which versions to maintain
- Create a deprecation notice template for older versions
- Establish a process for archiving very old versions
Signed-off-by: dhruv1955 <dhruvyadav042905@gmail.com>
dhruv1955
force-pushed
the
docs-structure-improvement
branch
from
b665745 to
b7b6ecb
Compare
2 participants
Summary
This PR adds a documentation-focused analysis describing the current structure of the Volcano website documentation, identifies observed pain points, and proposes incremental, low-risk improvements to improve maintainability and contributor experience.
Motivation
As Volcano continues to grow, having a clear and shared understanding of the documentation structure helps both maintainers and contributors plan improvements more effectively. This document is intended to serve as a reference for future documentation work without introducing breaking changes.
Scope
Follow-up
Future PRs may build on this document to implement specific low-risk improvements incrementally, based on maintainer feedback.