Updating Documentation
It's important to keep the documentation updated as the project evolves. Here are some brief notes about how to think about documentation for simple_deploy
, and some how-tos for maintaining the project's documentation.
Guiding principles
Audiences
There are four main audiences for the documentation:
- End users: People who want to use
simple_deploy
to deploy a project, and don't care about the internals of the project. - Authors and creators: People who want to use
simple_deploy
to teach others how to deploy and work with Django projects. - Developers: People who want to help develop
simple_deploy
, and keep it up to date. These are people who are working on simple_deploy locally, and who submit PRs to the project. - Maintainers: People who are managing the long-term development and stability of the project. These are people who can merge PRs and make new releases.
All documentation should target one or more of these specific groups.
Documentation sections
End-user documentation should be clear and to the point.
- People use
simple_deploy
in order to simplify deployment. The documentation that's written for them should support this mindset. - The main pages targeting this audience is the Introduction and Quick Start pages.
Documentation for authors and creators should include more detailed information and explanations, without focusing on the project's internals.
- These people need to know a little more about how
simple_deploy
can be used, so they can best determine how to write or speak about it, or otherwise integrate it into their work. - The main pages focused on this group are in the General Documentation section.
Documentation for developers should focus on design principles and project internals.
- These people need to understand some of the internals of
simple_deploy
. - The Contributing, Design Documentation, and Unit Tests sections are relevant to this group.
Documentation for maintainers should focus on project architecture, and maintenance tasks.
- This group needs to understand how to evaluate potential contributions to the project.
- This group needs to know how to carry out maintenance tasks for the project.
- The main section for this group is under Maintaining.
Documentation framework (MkDocs)
Documentation uses Material for MkDocs.
- All documentation lives in
docs/
. - The documentation configuration file
mkdocs.yml
lives in the root folder. - The main help page for maintaining an established Material project is here.
Updating documentation
- To update the documentation, modify any of the existing files in
docs/
. If you feel the need to create a new section in the docs, please bring this up in an issue or discussion first.
Viewing the documentation locally
To view the documentation locally, run mkdocs serve
in the root directory of the project, in an active virtual environment. Visit the project at http://localhost:8000
. If that port is in use, you can run mkdocs serve --dev-addr localhost:PORT_NUMBER
.
Releasing documentation
Updated documentation is automatically pushed to RtD once it's on the main branch. Every merge that involves documentation gets pushed automatically.