5.1. Writing effective documentation

Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, technical reference and explanation. People working with software need these four different kinds of documentation at different times, in different circumstances - so software usually needs them all, and they should be integrated into your documentation [doc].

	Tutorials	How-to guides	Reference	Explanation
oriented to	learning	a goal	information	understanding
must	allow the newcomer to get started	show how to solve a specific problem	describe the machinery	explain
its form	a lesson	a series of steps	dry description	discursive explanation
analogy	teaching a small child how to cook	a recipe in a cookery book	a reference encyclopaedia article	an article on culinary social history

For more information, see the following guide by Daniele Procida.

Additional resources:

• Tips

• Neutrality and inclusivity