1.4 KiB
Create examples of ranking complexity when documenting your project
Some projects such as user applications should include examples of usage varying of the complexity from a simple "Hello world"-esque example to a real-life example that the developer uses. This gives a quick introduction to the tool as well as subtly giving hints about what you can do with the program. Examples include the manual pages from the FreeBSD project where each tool is given a dedicated section for example usage. Another that stuck out to me is the README of maim, a screenshot capture tool, where one of the examples demonstrate that you can pipe binary output which leads to useful things such as OCR selection or a colorpicker.
This is not only useful for software documentation, it is also useful for technical writings. This makes it easier to skim (see Speedreading is all about skimming well) and to Learn more with referencing with a bit of remembering.