The current developer documentation is not consistently up-to-date and is of uneven quality. All the existing doc resources should be reviewed, lacking and incorrect information identified and organized into tickets.

Proposed procedure:

Using mkdocs.yml as the master list of pages, go page by page, section by section and:

1. Verify the content of each section

• Test the pieces of information that are testable
• Identify the domain expert and ask to check remaining information
• Check that quoted code is identical with source
• Check differences between doc versions

2. Identify issues

• Locate existing tickets related to the page and check if they are still valid
• Create tickets for issues that cannot be fixed instantly, with the doc-audit label
• Identify missing information by:
  • looking through related PRs
  • looking through release notes
  • asking domain experts

3. Note down all sections/information you were unable to verify!

• Add comments in a separate branch

4. Identify missing higher-level/conceptual doc, missing procedures, introductions, terms explanations and create issues (with the doc-audit label)

5. Check text coherence:

• Text flow, order of introducing concepts
• Logical sequence of sections, check for mentions of "this page" on larger combined pages
• Where necessary, add links to higher-level/conceptual explanations
• Re-check that existing links point to latest doc and to correct places in code
• Reformulate headings to better represent the content in a TOC (remember to update links on other pages!)
• Change heading levels where relevant to have a browseable TOC
• Look of unnecessary mentions of 5.x of Publish and for tenses: (e.g. remove future tense when referring to an existing feature)
• Where possible, integrate info/note boxes into text.
• Verify use of domain terms

Other:

• Locate pieces of doc hidden in other repos
  • Check their up-to-dateness
  • Decide if they can/should be moved to the main repo
• Look through 4.x doc
  • See which sections could use corresponding info in current doc