Documenting Domain-Specific Knowledge

“It might be the best thing ever but guess what, if you invent the best thing ever and don’t write any docs for it for 13 years, you lose” — Jean-Paul Calderone
What is a domain?

• A domain is something a person can be completely ignorant about in a subject while being an expert about everything else.
  Pick an audience
• An audience is a set of knowledge that you expect the people to come with and their goals.
• Docs should help the audience get their job done not be an archive of everything that can ever be known about a subject. You might know a lot about how the thing was designed or why certain decisions were made. That doesn’t mean that should be in the docs.
• You might need to write the documentation multiple times, once for each of these different personas.
  Straight line docs
• The best docs are the ones that keep you there
• Too many links to other places are distracting
• There’s nothing wrong with links to other places, but they should always be optional
• If it’s necessary, it needs to be in line so that people can follow and don’t miss something.
• If it’s optional, make it a link. If it’s just there for additional curiosity, take it out.
  No assumptions
• Eliminate all assumptions
• Avoid using jargon. Where jargon is necessary, explain it.
• Where words mean something other than their common meaning, explain the domain-specific meaning. (this is poor design but where it is unavoidable, explain it and, where possible, explain why you needed to use that specific word/phrase/term)
• This is what will make the bulk of those optional links to somewhere else. The somewhere else should not be a replacement for you to explain what it is but a place to go for more.
  Be prescriptive
• If you have subject-matter expertise, then make recommendations.
• Use the active voice.
• Don’t overwhelm the reader with all the options they might ever need. Recommend the ones they should use. Then you can provide optional links to other options.
• People who have opinions about how to do things probably aren't reading the documentation and looking for that information. Remember, you’re writing for a specific audience.
  Connect the dots
• Composition is a great way to build solutions. Dividing your problem into small chunks that can be solved independently and then put together to form complete solutions. It’s a great way to build almost anything.
• However, composition can be problematic for documenting to new people; they are not familiar with how you connect all the pieces. It’s your job when writing the documentation to show them how the unique pieces come together.
• Connect the dots for them. Show complete examples of how the individual pieces can be put together to solve bigger problems.
  Get someone to test your documentation
• Give someone a problem that can be solved by using your docs and look at how they use them. Anytime they reach for any other resource to improve their understanding, flag that as a bug in your docs.
• Rubber ducking works for docs too.
  Known Unknowns and Unknown unknowns
• Readers of your docs often don’t know what they don’t know. This is something that comes with learning new materials.
• Nothing of consequence should ever depend of something a user doesn’t know they don’t know. And it’s your documentation’s responsibility to inform them of everything they need to know.
  Always be improving
• Whenever you get questions about how do I solve this or what is that? Treat this as feedback for your documentation. It’s something you can improve.
• Not only should you take their feedback, but you should enable and encourage them to act on their feedback by contributing to the docs.
  Your documentation is one of your projects
• Many programmers treat documentation as a tax they need to pay to do their work. So you should try as much as you can to ensure that your docs get out of the way and aren’t an impediment to doing the job.
• This means that documentation is one of the projects in your care. When you list the things that are your responsibility, documentation should also be there front and centre.
• The best documentation is the one that no one talks about.