refactor: reorganize and rename documentation files for improved stru… #17
Conversation
…cture and clarity
Summary of ChangesHello @KUASWoodyLIN, 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 focuses on a comprehensive refactor of the project's documentation to enhance its structure, clarity, and overall user experience. The changes involve reorganizing existing content into more intuitive paths, introducing new detailed guides for critical setup and management processes, and updating the navigation system to seamlessly integrate these improvements. The primary goal is to make the documentation more accessible and easier to navigate for both new and returning users. Highlights
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
|
![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 pull request significantly refactors and improves the documentation structure by reorganizing files, adding an introduction and getting started guide, and clarifying sidebar navigation. The changes are well-executed and enhance clarity. My review includes suggestions to improve consistency in labels, clarify potentially ambiguous instructions, and adopt more maintainable and accessible formatting in the markdown files.
| label: 'basic', | ||
| translations: { | ||
| 'zh-Hant': '基本' | ||
| }, | ||
| autogenerate: { directory: 'basic' } | ||
| }, | ||
| { | ||
| label: '服務', | ||
| label: 'service', | ||
| translations: { | ||
| 'zh-Hant': '服務' | ||
| }, | ||
| autogenerate: { directory: 'service' } |
There was a problem hiding this comment.
For consistency with other capitalized sidebar labels like 'Introduction' and 'Getting Started', it would be better to capitalize the labels for 'basic' and 'service' as well.
| label: 'basic', | |
| translations: { | |
| 'zh-Hant': '基本' | |
| }, | |
| autogenerate: { directory: 'basic' } | |
| }, | |
| { | |
| label: '服務', | |
| label: 'service', | |
| translations: { | |
| 'zh-Hant': '服務' | |
| }, | |
| autogenerate: { directory: 'service' } | |
| label: 'Basic', | |
| translations: { | |
| 'zh-Hant': '基本' | |
| }, | |
| autogenerate: { directory: 'basic' } | |
| }, | |
| { | |
| label: 'Service', | |
| translations: { | |
| 'zh-Hant': '服務' | |
| }, | |
| autogenerate: { directory: 'service' } |
|
|
||
| | Service Group | Port(s) | Domains | | ||
| | :---------------------- | :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | **Canonical Services** | TCP 443 (HTTPS)<br>TCP 80 (HTTP)\* | `api.charmhub.io`, `api.jujucharms.com`, `changelogs.ubuntu.com`, `charmhub.io`, `cloud-images.ubuntu.com`, `maas.ubuntu.com`, `images.maas.io`\*, `juju.is`, `jaas.ai`, `streams.canonical.com`, `objects.githubusercontent.com`, `contracts.canonical.com` | |
There was a problem hiding this comment.
The asterisks next to (HTTP)* and images.maas.io* seem to indicate a footnote or special condition, but there is no corresponding explanation in the document. Please add a note to clarify what the asterisks mean to avoid confusion.
| Execute the installation script through the User Interface: | ||
|
|
||
| 1. Access the OtterScale UI. | ||
| 2. Execute the `install.sh` script. |
There was a problem hiding this comment.
The instruction 'Execute the install.sh script' through the UI could be more specific. To improve clarity for the user, consider explaining how to execute the script from the UI. For example, is there a button to click, or a command provided in the UI to be run elsewhere?
| - **Label**: Scope Name <span style="color: #eab308">●</span> | ||
| - **Description**: Enter a unique name for your scope. | ||
| - **Input**: Text field (Required). | ||
|
|
||
| #### Machine Selection | ||
|
|
||
| - **Label**: Machine <span style="color: #eab308">●</span> | ||
| - **Description**: Select the physical machine to assign to this scope. | ||
| - **Input**: Dropdown menu. | ||
| - The dropdown lists available machines that are in the `Ready` status. | ||
| - Hovering over the info icon <span class="iconify" data-icon="ph:info"></span> next to a machine name displays detailed hardware specifications (CPU, Memory, Storage, System info, etc.). |
There was a problem hiding this comment.
Using raw HTML like <span style="color: #eab308">●</span> (line 33) and <span class="iconify" ...></span> (line 43) to render UI elements in Markdown can be brittle and hard to maintain. It may also present accessibility issues.
Consider using a more semantic and standard Markdown approach. For example:
- For required fields, you could add
(Required)text next to the label. - For icons, you could use an emoji or a shortcode if your framework supports it.
This would make the documentation cleaner and more resilient to future style changes.
| @@ -0,0 +1,38 @@ | |||
| --- | |||
| title: Get Started | |||
There was a problem hiding this comment.
The title of this page is 'Get Started', but the file is named introduction.md and its sidebar label is 'Introduction'. For consistency, it would be better to change the title to 'Introduction'.
| title: Get Started | |
| title: Introduction |
There was a problem hiding this comment.
Pull request overview
This PR refactors the documentation structure by reorganizing files into logical sections (getting-started, basic, service) with numeric prefixes for ordering, creating comprehensive new documentation pages, and updating the navigation configuration accordingly.
Key Changes:
- Reorganized documentation into three main sections: Getting Started, Basic, and Service
- Created detailed documentation for prerequisites, installation, scope management, machines, networking, configuration, applications, compute, models, storage, and settings
- Updated Astro configuration to reflect new structure with proper translations and autogeneration
- Replaced outdated
/guides/example/link with/introduction/in the main hero section
Reviewed changes
Copilot reviewed 8 out of 17 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
src/content/docs/introduction.md |
New comprehensive introduction page explaining OtterScale's architecture, features, and next steps |
src/content/docs/getting-started/01-prerequisites.md |
Detailed prerequisites including system requirements, hardware specs, network configuration, and firewall rules |
src/content/docs/getting-started/02-installation.md |
Step-by-step installation guide with Docker Compose setup and configuration |
src/content/docs/getting-started/03-scope.md |
Comprehensive scope management guide including creation process, plan selection, and configuration details |
src/content/docs/basic/01-machines.md |
Documentation for managing physical and virtual machines |
src/content/docs/basic/02-networking.md |
Networking configuration documentation |
src/content/docs/basic/03-configuration.md |
Global configuration settings documentation |
src/content/docs/service/01-applications.md |
Application management documentation covering workloads, services, secrets, and store |
src/content/docs/service/02-compute.md |
Virtual machine management documentation |
src/content/docs/service/03-models.md |
LLM model management documentation |
src/content/docs/service/04-storage.md |
Storage resources management documentation |
src/content/docs/service/05-settings.md |
Application-specific settings documentation |
src/content/docs/create-scope.md |
Simplified scope documentation (appears to be a duplicate) |
src/content/docs/index.mdx |
Updated hero link to point to new introduction page |
src/content/docs/get-started.md |
Removed old getting started page in favor of new structure |
astro.config.mjs |
Updated sidebar configuration with new sections, translations, and locales export |
src/content.config.ts |
Removed trailing comma from collection definition |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Installation Process | ||
|
|
||
| ### 1. Start Services |
There was a problem hiding this comment.
[nitpick] Consider adding a blank line after the heading on line 8 and before the subheading on line 10 for better readability and consistency with markdown formatting best practices.
| }, | ||
| { | ||
| label: '服務', | ||
| label: 'service', |
There was a problem hiding this comment.
The label for the 'service' section should be capitalized as "Service" to maintain consistency with other section labels like "Introduction" and "Getting Started".
| label: 'service', | |
| label: 'Service', |
| label: '基礎', | ||
| label: 'basic', | ||
| translations: { | ||
| 'zh-Hant': '基本' |
There was a problem hiding this comment.
[nitpick] Consider making the translation key more descriptive. The Chinese translation '基本' means 'basic' or 'fundamental', while '基礎' (which was used before) means 'foundation' or 'basics'. If you intended to change the meaning, this is correct, but if not, consider reverting to '基礎' for consistency.
| 'zh-Hant': '基本' | |
| 'zh-Hant': '基礎' |
|
|
||
| export const collections = { | ||
| docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }), | ||
| docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }) |
There was a problem hiding this comment.
[nitpick] Removing the trailing comma is inconsistent with modern JavaScript/TypeScript best practices, which recommend trailing commas in multi-line object/array literals for cleaner diffs. Consider keeping the trailing comma.
| docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }) | |
| docs: defineCollection({ loader: docsLoader(), schema: docsSchema(), }) |
| - The dropdown lists available machines that are in the `Ready` status. | ||
| - Hovering over the info icon <span class="iconify" data-icon="ph:info"></span> next to a machine name displays detailed hardware specifications (CPU, Memory, Storage, System info, etc.). |
There was a problem hiding this comment.
Inconsistent list formatting. Line 42 uses a hyphen (-) for the list item, while line 43 uses two spaces and a hyphen. All sub-items under "Input" should consistently use the same indentation level (either 2 or 4 spaces).
|
|
||
| { | ||
| label: '基礎', | ||
| label: 'basic', |
There was a problem hiding this comment.
The label for the 'basic' section should be capitalized as "Basic" to maintain consistency with other section labels like "Introduction" and "Getting Started".
| label: 'basic', | |
| label: 'Basic', |
|
|
||
| ## Next Steps | ||
|
|
||
| - [Check Prerequisites](/getting-started/01-prerequisites) |
There was a problem hiding this comment.
The "Next Steps" section links to Prerequisites (01) and Create a Scope (03), but skips the Installation guide (02). Consider adding a link to /getting-started/02-installation between the prerequisites and scope creation steps for a complete getting started flow.
| - [Check Prerequisites](/getting-started/01-prerequisites) | |
| - [Check Prerequisites](/getting-started/01-prerequisites) | |
| - [Install OtterScale](/getting-started/02-installation) |
| - This section appears after you select a machine. | ||
| - It lists available non-boot block devices. | ||
| - Hovering over a device shows its model and capacity. |
There was a problem hiding this comment.
Inconsistent list formatting. Lines 50-52 have inconsistent indentation. Line 50 uses a hyphen at the start, while lines 51-52 use two spaces before the hyphen. All sub-items should use consistent indentation.
…cture and clarity