Add doc` directories to plinth and inner django modules. Write developer documentation in GH-flavored markdown format.
This convention of shipping developer documentation within the repository can be followed in other FreedomBox projects as well.
The developer documentation on the wiki at Manual/Developer hasn’t been updated in years.
The documentation being maintained in a separate wiki and not being in version control is a classic anti-pattern we have to avoid.
A lot of design decisions and implementation details are spread across git commit messages and GitLab issues, neither of which are easy to refer to during development.
Keep developer documentation in version control and included within the repository that it’s relevant to.
This documentation can explain design decisions, implementation plan, tech debt etc.
Individual app modules can have their own
doc directory since they might be shipped independently in the future. The outer plinth module itself can also have a
doc directory which contains more general documentation like “how to create a FreedomBox app”.
(We already have a
doc directory at root of the Plinth repository which contains the user manual extracted from the wiki.)
Merge requests can be raised with documentation included.
Having the documentation in a directory with markdown files keeps it independent of the git web tool we use as compared to using GitLab wiki.
It also allows offline and version-controlled historical references.
- Import the current developer documentation from Debian wiki
- Convert to GH-flavored markdown format using pandoc (this allows for easy reading directly on GitLab)
- Commit the .md files under plinth/doc
- Write any new developer documentation in the relevant files in