The documentation should be written in the second person, referring to the reader as “you” and not using the first person plural “we”. The author of the documentation is not sitting next to the user, so using “we” can lead to frustration when things don’t work as expected.
Avoid words that trivialize using Plug'in such as “simply” or “just”. Tasks that developers find simple or easy may not be for users.
Write in the active tense, so "check the IP address with..." rather than “the IP address can be checked with..."
The beginning of each section should begin with a short (1-2 sentence) high-level description of the topic, feature or component.
Use “enable” rather than “allow” to indicate what Plug'in makes possible for users. Using “allow” connotes that we are giving them permission, whereas “enable” connotes empowerment.
The seven rules of technical writing:
- Write in two steps: Focus on ideas and then on reviewing and shaping your text.
- Target the readership: Who is going to read it?
- Use a simple style: Keep it straight and simple. Use good grammar.
- Limit the scope of the information: Introduce one concept at a time.
- Use realistic code examples: "Foos" and "bars" should be avoided.
- Use a light but sufficient approach: You are not writing a book!
Use templates: Help the readers to get habits.
Write documentation that sells. It is what will convince others that the project is worth working in.
Write Code Any Engineer Can Read¶
Your code has to be written so it's simple for outside engineers to understand.
- Refactoring your code to be as simple as possible
- Following style conventions for names, whitespace, etc. (i.e. PEP8 for python)
- Replacing private information with environment variables
- Commenting your code to contextualize snippets within your broader codebase.
There is an enormous bunch of books describing the best practices to write in each language as well as in a general manner and helping to structure your code. You are invited to read and consult them regularly.
- Clean Code: A Handbook of Agile Software Craftsmanship - Robert C. Martin - ISBN-13: 978-0-13-235088-4 - ISBN-10: 0-13-235088-2 (Give a glance at the bibliography and references in this one)
- Beautiful Code - Edited by Andy Oram and Greg Wilson ISBN-10: 0-596-51004-7 - ISBN-13: 978-0-596-51004-6
- Refactoring: Improving the Design of Existing Code by Martin Fowler
- Expert Python Programming Second Edition - Michał Jaworski/Tarek Ziadé - ISBN 978-1-78588-685-0
- Freely available programming books
In this repository, the chapter for language agnostic
Style guide for Python follow PEP8
- Google style guide for JAVA
- Bjarne Stroustrup's C++ Style and Technique FAQ
- Google C++ Style Guide
- If you want to understand the underlying OS machinery, give a look at Think OS A Brief Introduction to Operating Systems by Allen B. Downey