Jason Morris
02/28/2023, 6:11 AMJarno Montonen
02/28/2023, 6:56 AMLu Wilson
02/28/2023, 7:00 AMguitarvydas
02/28/2023, 9:56 AMEli Mellen
02/28/2023, 12:29 PM<puts on professional documentation person hat>
I think a key to most great documentation is that it does 1 of the following, and doesnât try to be everything for everyone all at once. It picks a lane, and runs with it:
⢠Tutorials, learning-oriented (teaching someone to cook)
⢠How-to guides, problem-oriented (a recipe for cooking a specific thing)
⢠Explanation, understanding-oriented (historical overview of an ingredientâs cultural importance)
⢠Reference, information-oriented (an encyclopedia article about an ingredient)
Each of these types maps fairly well to an audience:
⢠Tutorials are for folks who are totally new to a thing
⢠How-to guides are a step up from tutorials and help you learn idioms and best practices of a space
⢠Explanation is useful when needing to convey the value of a thing
⢠Reference is generally for experts who are cozy doing the thing
When you are writing your docs., are they really descriptive? Do they have a specific audience(s) in mind?
Having a clear idea of your âideal documentation readerâ in mind, can help keep them manageable, since it can let you focus on not having to documenting everything and instead just whatâs needed for your goals.
</doffs documentation person hat>
Jason Morris
02/28/2023, 6:33 PM