Skip to content

Contribute documentation

Learn how to write and contribute technical documentation.

References

Guidelines

Before starting

  • Set up a spell checker in your IDE, even better a "writing assistant" (popular ones LanguageTool, Grammarly).
  • Determine what your audience needs to learn, fit documentation to your audience.

When writing

  • Write in the second person. Refer to your audience as “you” rather than “we”.
  • Create great opening sentences that establish a paragraph's central point.
  • Prefer active voice to passive voice: The mat was sat on by the cat. -> The cat sat on the mat.
  • Prefer task-based headings.
  • Prefer list to long sentences. Use a numbered list when ordering is important and a bulleted list when ordering is irrelevant.
  • Explain and give information progressively.
  • Usage sections should feel like tutorials that call the user to action - e.g. "create a mapping".
  • In tutorials, reinforce concepts with examples, note problems that readers may encounter.

When completed

  • Read documents out loud (to yourself).
  • Ask for review.
  • When using MkDocs, run the live server and verify that the page renders correctly (e.g. code snippets).

External locations to update

When updating the documentation, you may move content and pages around that some modules of the InvenioRDM project link to. You will need to update those links to point to the moved pages. In particular, verify if your changes affect the links listed in these locations: