Your documentation should be:
👥 Inclusive and clear
Write docs in an inclusive and clear manner. Your language should be easy to understand and inviting. Try not to make assumptions about user's base level knowledge.
Easy to read documentation is an easy way to increase number of users and contributors to your project.
✅ Complete
Describe all aspects of your project. Try to document all of the common use cases.
💡 Support queries are usually holes in your documentation. If you find yourself answering to questions about your project, which could have been 'searched', you should add that to your documentation.
✨ Up-to-date
This is particularly hard. Outdated documentation might cause more harm than no documentation at all.
For Python projects, doctests does help to a certain extent in keeping documentation up-to-date, but really the onus of maintaining the docs lies on the developer.
💡 Adding documentation as a measure of completeness of coding tasks is very helpful.
💻 Easy to contribute
Add clear instructions on how to contribute to your project. This may include coding guidelines and standards, running test suites etc.
🔍 Easy to find
If working on "inner source" projects, make sure your project is searchable within your organization. Some companies use Confluence/Sharepoint to host docs, you may be able to keep a static landing page that may point to your project's homepage, which might be generated dynamically.
Top comments (0)