Deliverable 1: Overview of the different types of documentation¶
t.b.d.:
- Integrate categories proposed by Dirk R., Kerim, Liliana into a single diagram/schema that shows the different types of documentation
- Dirk Roorda:
- application layer: technical docs - within the code
- deployment layer: maintenance docs - docs/deployment
- project layer: stakeholders - docs/about page
- user layer: docs/manual, docs/tutorial, notebooks
- readme.md: links to all the above
- Kerim:
- Readme
- Aimed at technical users; it lives with the code. Contains architecture, models used, API, configuration, services to call and installation/build/extension instructions.
- Production (and other environments) deployment configuration
- Used to have a backup and reference location of our (production) deployments. Contains secrets, so only accessible in the internal GitLab.
- Software development / knowledge base
- An environment where we keep track of idea's, technical documentation and overviews that we cannot place anywhere else
- User manuals
- User manuals aimed at end users explaining how to work with a piece of software. Are often created by the end users themselves.
- Websites
- Used to collect all information/documentation in one place and to share with interested users.
- Work in progress
- Readme
- Liliana:
- Adding to the above:
- Websites → DI Portfolio
- idea: create a kind of “matrix“ between: documentation types, users per each type, where it’s kept, and guidelines per type?
- Adding to the above:
- Zefi:
- Also extending on the above:
- Repository naming conventions to increase clarity
- File and folder naming conventions e.g. what delimiters to use, etc
- Maarten: Such conventions also differ regarding the language ecosystem used, so I don't think there's a one-way-catch-all convention ..
- Directory structure: an agreed-upon structure that separates product code from potential deployment code, is conventional across DI and can be used to automate maintenance or display of docs e.g. with codemeta, mkdocs magicspace, pdoc3, etc
- Also extending on the above:
- Maarten:
- I may be stretching the term documentation a bit here, but accurate software metadata and accurate versioning practices can be considered a form of documentation too. I think it's important that:
- metadata (e.g. in pyproject.toml, package.json) are kept up to date and accurate
- developers provide sensible commit messages for version control
- make sure you commit with a properly set author (your full name, proper mail).
- software is released periodically with a version number following semantic versioning
- I may be stretching the term documentation a bit here, but accurate software metadata and accurate versioning practices can be considered a form of documentation too. I think it's important that:
Bij website data, let op dat het wel/niet beschikbaar blijft. Info kan ook in een repo op worden genomen zodat het behouden blijft. Alle info over deelnemers in de readme file, kan overbodig lijken (er is ook een website), maar wanneer de website weg is of veranderd, kan deze data ook weg zijn.