Homogenize /docs directory making sure it follows the instructions in .github #21
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Co-authored-by: kozo2 <12192+kozo2@users.noreply.github.com>
Co-authored-by: kozo2 <12192+kozo2@users.noreply.github.com>
Homogenize /docs directory following CrackingShells documentation instructions
There was a problem hiding this comment.
Pull Request Overview
This PR restructures and standardizes the documentation to align with the project’s .github guidelines.
- Removes the old usage index in favor of a unified docs structure.
- Adds consistent intro sections and “You will learn about” bullets across all user and developer guides.
- Introduces a top‐level index, a table of contents, and reorganizes content into user, developer, and appendix directories.
Reviewed Changes
Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/usage/index.md | Removed deprecated usage index |
| docs/index.md | Added intro bullets, Quick Navigation, and updated structure |
| docs/articles/users/SchemaValidation.md | Standardized intro sections and fixed relative links |
| docs/articles/users/SchemaAccess.md | Standardized intro, clarified distribution methods |
| docs/articles/users/RegistrySchema/Overview.md | Renamed title, added intros, and corrected link casing |
| docs/articles/users/RegistrySchema/Fields.md | Added intro bullets |
| docs/articles/users/ProgrammaticUsage.md | Standardized intro, corrected typo, updated See Also links |
| docs/articles/users/PackageSchema/Overview.md | Renamed title, added intros, corrected link casing |
| docs/articles/users/PackageSchema/Fields.md | Added intro bullets |
| docs/articles/users/PackageSchema/Examples.md | Added intro bullets and updated See Also links |
| docs/articles/users/GettingStarted.md | Added new Getting Started guide with structured intro |
| docs/articles/table_of_contents.md | Added new Table of Contents for top‐level navigation |
| docs/articles/devs/SchemaVersioning.md | Added Schema Versioning doc with standardized intro |
| docs/articles/devs/RepositoryStructure.md | Added Repository Structure doc with standardized intro |
| docs/articles/devs/DevelopmentSetup.md | Added Development Setup doc with standardized intro |
| docs/articles/devs/Contributing.md | Added Contributing Guidelines doc with standardized intro |
| docs/articles/appendices/glossary.md | Added Glossary appendix with structured intro |
Comment on lines
+31
to
34
| For detailed field-by-field documentation including types, formats, and examples, see the [Registry Schema Field Reference](Fields.md). | ||
| - **verification**: Verification status and metadata | ||
| - **dependency_changes**: Changes to dependencies since the base version | ||
| - **compatibility_changes**: Changes to compatibility requirements |
There was a problem hiding this comment.
[nitpick] This link to the Registry Schema Field Reference is also repeated in the See Also section; consider removing the duplicate to reduce redundancy.
Suggested change
| For detailed field-by-field documentation including types, formats, and examples, see the [Registry Schema Field Reference](Fields.md). | |
| - **verification**: Verification status and metadata | |
| - **dependency_changes**: Changes to dependencies since the base version | |
| - **compatibility_changes**: Changes to compatibility requirements | |
| - **verification**: Verification status and metadata | |
| - **dependency_changes**: Changes to dependencies since the base version | |
| - **compatibility_changes**: Changes to compatibility requirements | |
| - **compatibility_changes**: Changes to compatibility requirements |
kozo2
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The file that contains the instructions is
https://github.com/CrackingShells/.github/blob/main/instructions/documentation.instructions.md .
Update the dev branch of this repository according to https://github.com/CrackingShells/.github/blob/main/instructions/documentation.instructions.md .