Skip to content

Documentation

General

  • In repository: what to include (depending on project type)
  • Markup format: MD or Asciidoc
  • Location: root of project
  • README (what to include… template?) [Policy]
    • Content [Guidelines] - GitHub: Formatting your README
      • Project name
      • Description
      • Table of Contents (optional)
      • Installation -> INSTALL
      • Usage
        • Requirements (runtime, dependencies)
        • How to build
        • How to run
      • Contributing -> CONTRIBUTE
      • Credits
      • License -> LICENSE
  • LICENSE [Policy]
    • See ‘Code license section’
  • INSTALL (what to include… template?)
    • Content? [Guidelines]
  • UPGRADE (what to include… template?)
    • Content? [Guidelines]
  • CHANGES / Release notes
  • CONTRIBUTING - GitHub: Setting guidelines for repository contributors
    • We will make a general contributions guideline to include by default in all projects
    • A custom contributions guideline document can be made, describing:
      • Pull request policy
      • Issues policy
      • Branching model
      • ..
  • ..

Design and project documentation

  • Requirements & architecture design
  • Roadmap

End user documentation

  • In what cases is it needed?
  • Where
  • Where/how can the user find it
  • Where is it maintained (and how is it integrated)
  • In what format

“Stand alone” documentation (in a broad sense, e.g. this handbook) should be published under a CC-BY 4.0 licence (“Creative Commons - Attribution 4.0 International”).