We've learnt a couple of things in this module.

  • Both the content of your documentation and its presentation are important, and are dependent on your audience.
  • Reference material and conceptual material are two main kinds of documentation.
  • Reference docs give users the information they need to make their own paths., while conceptual docs guide them along paths you've selected.
  • Depending on your API's size, you need the right mix of both reference and conceptual docs, either separately or combined.
  • Set expectations for what you want and don't want from your documentation. To do this, you need to actively put yourself in your users' shoes.
  • Some things you don't want from your docs: incorrectness, incompleteness, bloat, inconsistency, obscurity, ambiguity, fragmentation.
  • Some things you want from your docs: correctness, completeness, conciseness, consistency, clarity, accessibility. 
  • Always think of your users' needs.

We've also looked at some specific documentation patterns and seen how they impact the user experience. In the next module, we'll apply these principles as we design a documentation workflow.

Let's take a step back...

How are you feeling? Excited? Overwhelmed? Intimidated? Hopefully not intimidated. Now, it MIGHT seem a bit overwhelming with all that we've seen and learnt in this module. It might seem like it would take a lot of work and you might be wondering how you'll do it. 

But have no fear, you CAN do it! Documentation isn't easy, but there are tools you can use that get rid of a lot of the stress. Plus, you can apply your dev skills to work magic too. So hang in there, and follow the process. And I promise you, it's all going to be worth it. On to the next!

Complete and Continue