Skip to content

Documentation restructure#330

Open
martyn-fewtrell wants to merge 7 commits into
mainfrom
feature/restructure
Open

Documentation restructure#330
martyn-fewtrell wants to merge 7 commits into
mainfrom
feature/restructure

Conversation

@martyn-fewtrell

Copy link
Copy Markdown
Contributor

PR Classification

Documentation restructure and content update.

PR Summary

This pull request restructures the documentation repository for improved clarity, navigation, and consistency, updating content and internal links to match a new organizational scheme.

  • Adds new README files for each top-level area (communities, policies, standards, guidance, reference) with clear entry points and related links.
  • Introduces a comprehensive documentation guidance file detailing documentation modes, structure, and contributor checklists.
  • Updates the main README to serve as a content map with audience journeys and area links.
  • Refactors and relocates policy, standard, and guidance documents, updating references and internal links throughout.
  • Rewrites CONTRIBUTING.md to align with the new structure and document mapping guidance.

Add documentation.instructions.md with detailed authoring guidance, including documentation modes, mapping, and a contributor checklist. Update CONTRIBUTING.md with a mapping table for document types. Revise README.md files to clarify the purpose and navigation of each documentation area.
@snyk-io-eu

snyk-io-eu Bot commented May 14, 2026

Copy link
Copy Markdown

Snyk checks have passed. No issues have been found so far.

Status Scan Engine Critical High Medium Low Total (0)
Open Source Security 0 0 0 0 0 issues
Licenses 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

Updated list markers in README.md to use consistent Markdown formatting. Changed '-' to '*' and vice versa in relevant sections to align with best practices. No content changes were made.
Minor formatting adjustments were made to the "Contents" list in README.md by adding extra spaces after some items. These changes enhance the visual consistency of the documentation without altering any content.

@elerivaliant elerivaliant left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I like about this:

  • Relative links
  • More logical structure

Less happy with:

  • The introduction of a lot of pages that are just lists of content. It feels like you would never be able to edit anything here again without AI having to be involved to make sure you haven't broken links.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants