Technical Documentation: My Personal Framework for a Better Guide
I’m working on putting together a sort of personal framework for writing technical docs for software projects.
The idea is to keep the docs fresh and helpful without them getting stale too fast.
Here’s what I’m thinking the framework should cover:
- Figuring out what kind of docs you need for your project.
- Getting a sense of how to organize all this info.
- Deciding how detailed or high-level each doc should be.
The tricky part is, there’s no one-size-fits-all answer for this stuff. Like, what docs are essential, when to stop adding more, and how detailed they need to be — it varies a lot. Templates can be handy, but they only get you so far.
So, what if we go for a set of guiding principles and a flexible process instead? This way, you can sort out these questions as you go along.
Then let’s start with
Principles
Every Document Should Have ONE Specific Goal
- Introduce to the matter (Overview)
- To teach the reader (Guides)
- To perform a specific task (Tutorials)
- To explain how it works (Manuals)
- To present the findings (Research)
I will try to cover them in other articles, but for now let’s just focus on overall process.
Important to keep every document align to it’s goal. Review the document after creation and remove or move everything that does not serve the document’s goal. If you find it hard to choose what to write, write everything first, then remove or hide unnecessary parts. This will make your documents much shorter and more understandable.
However, do not hesitate to include links to documents that explain certain parts or concepts in more detail.
Show, Don’t Tell
It’s better to start with diagrams rather than words: process flows, architecture (C4), etc., and then explain the diagrams with words. I’ve found that Mermaid + PlantUML, which are easy to update with changes, work best for this purpose, and AI tools help a lot with the basic structure of the diagram. But of course, you can use anything you like.
versus:
Show an example. Even a simple example helps significantly with understanding:
versus
Which one is more useful?
Be Explicit
If something needs to be done that is not part of the document, such as tool installation, preparing data in advance, etc., provide links to the corresponding documentation, do not force reader to look for them.
Do Not Assume
You need to understand your audience, so be wise in your assumptions.
Do not assume the specific background knowledge of the person reading the document. Avoid presuming that the user has everything prepared, understands the context, grasps the concepts, or has already read other documentation. Provide links (as references) to every piece of information that needs to be known in advance.
Use the Principle of Least Astonishment (POLA), also known as the Principle of Least Surprise
Always cover “gotchas” and non-typical usage, structure or behavior.
What Documents Should Be Created?
As I already mentioned, there is no universal answer to this, but I’ve come up with a process that helps to answer this question most of the time:
- Start with Tutorials.
- Create an overall review and generic architecture.
- Cover specific topics with Guides.
- (Optional) Create Manuals.
Start with Tutorials
Take typical actions that someone will perform in the future and explain how to do them in detail. Do not explain how it works or add any unnecessary information — it should contain a simple list of steps to perform to achieve a specific goal.
You can illustrate the process with a diagram, though.
This is a great way to start — you begin creating useful documents right away, and better understand the level of abstraction for other documents, along with “gotchas” that need to be covered in the documentation.
Next: overall review and generic architecture
This is works great as intro for reader. It should not contain any technical details (except, maybe, dependencies and requirements, if this is short list). The goal is to have shortest document possible, explains purpose of the things, general structure of interactions with other parts of the system or other systems. This one should contain links to other documents.
Next: Cover Specific Topics with Guides
Complex projects require additional effort to teach the reader how they work and how to use them properly, so for this, Guides will be useful. Remember, the goal is to teach — so ensure that anything you add can be tried by the user.
“Show, don’t tell”: use examples wherever possible (it’s better if the code is in a repository, so users can try it), include video materials, diagrams, and screenshots for clarity.
A Guide may become a set of documents instead of one, due to the nature of the document, but don’t worry — write one comprehensive document, then split it into separate ones if the topics covered do not fit the purpose of teaching a specific thing.
Optional: Manual
This one is the hardest to do properly. Ideally, it should contain everything a user needs to know about how the project works, why it is structured that way, and how to use it. It is really challenging to get it right at the appropriate level of abstraction.
I suggest starting by explaining how everything works, from the most general to the most detailed parts, and figuring out the right level in the process. Diagrams are very helpful in creating this (even if you want to have some “classic” text manuals).
Remember to cover unintuitive aspects.
How Should the Documentation Structure Look?
Do not worry about placement and structure at the beginning.
It does not matter where you initially create the document. You can always move it to the right place after its creation.
It is even better if you create the structure later, after the documentation has been created, because we tend to limit ourselves with a pre-designed structure, which is not always helpful.
Some closing advises
- Do not be afraid to repeat or duplicate information
The DRY (Don’t Repeat Yourself) principle does not apply to documentation in the same way it does to code. Some contextual information can and should be duplicated in different documents to prevent the user from guessing what is going on when jumping into the middle of the process. Just try to be more generic and link to documents with more specific information.
Many links to the same document are okay. - Do not be afraid to create “simple” and “straightforward” documents
Some documents are never created because they seem “too simple” for the author, leaving potential readers guessing what they should do. Remember, do not assume. If it’s simple, then creating a document for it should be simple too, right? Then do it. You can always remove it later if it’s not helpful, but in my experience, “straightforward” documents are extremely helpful in the initial stages of exploring, effectively flattening the learning curve. - Use convenient tools for documentation
Tools like Obsidian can make a huge difference in the process experience. It is not fun to make documentation in online editors (at least, for me). Find one that you really like. You will not write documentation if you hate the editing process. For technical documentation markdown is the best IMO.
Creating good documentation is hard. Don’t try to make it perfect right away — instead, cover what is needed right now and improve it next time. Remember — just like code, documentation deteriorates over time, so always take some time to improve and update it. Like code, documentation is written once but read hundreds of times, so your effort will save dozens, if not thousands, of hours, and the journey will make you a better engineer, I promise.
