Documentation is essential for maintaining a successful organization. Furthermore, clean, organized documentation is ideal for clear communication and essential for well-maintained software and technical systems.
What is the Grand Unified Theory of Documentation?
The Grand Unified Theory of Documentation sorts documentation into four types:
- Tutorials—Guide the reader to a predetermined goal
- How-to guides—Address a specific problem for someone with experience
- Explanations—Explain and clarify a particular topic
References—Describe the technical details but do not explain concepts or achieve tasks
Diagram Credit of https://docs.divio.com/documentation-system/
Why is it important to separate documentation types?
Separating documentation keeps it clear and concise. It also allows people with different levels of experience with a system to use, learn, develop, and engineer that system.
Who would read the different types?
Tutorials are generally for beginner developers learning how to use a system. They should focus on helping the reader learn using practical steps.
How-to guides are for more experienced developers or system users who are trying to address a specific problem. They should focus on specific steps to address the problem.
Explanations are used by beginning developers studying the processes and workings of systems. They focus on theoretical knowledge to aid understanding of general system processes.
References are for experienced developers working on a new system to understand the background processes of the system. They focus on the background information developers would need while working.
How has this documentation theory been applied at OIT?
The OIT developer documentation standards highlight how the App Engineering Team has applied the documentation theory. Their Audiences and Documentation Types Table highlights the types of documentation each group will need, adding an additional category of documentation called Entry Point.