How to Document Well*

Version 1 of how to document programs well

Transcript

1. How to Document Well* Asher Glick V1.0
2. Three Key Parts to Documenting Understandable Comments in Code Provide Screenshots or Pictures Wiki pages or Document Pages Install instructions or Setup How to use the program Dev environment Setup
3. Understandable Comments in Code When people are reading your code, including yourself, they need to be able to understand what the code does without analyzing each line of code
4. Understandable Comments in Code Don't Comment Every Line This is worse than no comments because now whomever is reading the code has to read twice as many lines
5. Understandable Comments in Code Don't only comment parts you don't understand You will forget even the lines you did understand
6. Understandable Comments in Code Write a short statement what each function does If you see that function called you can easily figure out what it does
7. Understandable Comments in Code Write a short statement what each function does If that function is spitting out the wrong result you can easily discover that it is the problem
8. Understandable Comments in Code Write a short statement for large blocks of code or conditional statements Because those should really be separate functions
9. Provide Screenshots or Pictures Screenshots help the user decide if they want to use the program before they download or install it
10. Provide Screenshots or Pictures Screenshots help developers figure out what is wrong when they see something that is out of place
11. Provide Screenshots or Pictures Don't provide fake screenshots or UI that does not exist This confuses users disappoints them when they install or use the software They can be used as a "planned feature mockup" with proper identification
12. Wiki Pages or Document Pages The first three pages of documentation 1) Install instructions or Setup 2) How to use the program 3) Dev environment Setup
13. The most important page! Wiki Pages or Document Pages Install instructions or Setup
14. Wiki Pages or Document Pages Install instructions or Setup If the user does not know how to get the program on their computer they can't fathom using it
15. Wiki Pages or Document Pages How to Use the Program The user must know how to use the program How can they use it if they don't know how
16. Wiki Pages or Document Pages Developer Environment Setup After the end-users are taken care of make sure the developers know how to setup the environment to develop in
17. Next Version (2.0) Examples with and without good comments Pictures (Screenshots) because I said I should Example documentation pages Better Graphics, less words