The Cost of Bad Documentation and How to Fix It

What you'll learn in this episode

• The price of bad documentation
• Why good documentation is important
• What makes documentation good

How to support the show

Patreon

Prices subject to change and are listed in USD

• Support the show from as little as ~$1/month
• Get a shoutout at the end of the episode (while supplies last) for just ~$3/month
• Help support the HTML All The Things Podcast: Click Here

Scrimba Discount!

We receive a monetary kickback when you use our link

• Learn to code using Scrimba with their interactive follow along code editor
• Join their exclusive discord communities and network to find your first job!
• Use this URL to get 10% off on all their paid plans: https://tinyurl.com/ScrimbaHATT

Topics

Intro

• While it's almost a meme at this point that people don't check documentation and do everything they can do avoid it, there are a lot of us (myself included) that reach for documentation all the time to understand topics from the perspective of the source 
  - We've all been brand new to framework, a plugin, or a service and needed to reach for documentation 
  - The same goes for getting stuck on a problem, sometimes StackOverflow and ChatGPT don't have the answers we need so we need to reach for the official documentation
• Good documentation should have you in and out as quickly as possible, this isn't an SEO-centric blog post with needless intros and explanations, and it needs to be easy to understand

What makes documentation bad?

• Missing content
• Not up-to-date to the latest product version
• Incorrect instructions
• Unclear instructions 
• Inconsistent language
  - For example you always say press "publish" button but then you say "Save" the article later in the instructions. Is that a different action?
  - Saying terms that are similar to what is on the product's UI but not the same, especially in a step-by-step guide
• Talking as if the user has context and previous knowledge, especially if this sort of language is used in a beginner's guide or "my first app"
  - If possible, try and link to other articles and guides that would give them the context 

The price of bad documentation

• Wasted time
• Poor implementation of tech (devs are forced to cobble something together)
• Varying opinions in the community on something concrete
  - If it's unclear what the "official" way is, the cobbling together of methods that work may result in arguments over the best way to do it
  - Sometimes there is an objectively best way and if there is it needs to be clearly stated in the documentation 
  - Security issues due to poor implementation
• The product creator may have issue updating/upgrading the software as people may be mis-using it, making future updates break people's implementations unexpectedly
• Lost customers to competitors that were easier to set up
• Distrust among community members (people may make their own set of guides on the running joke that your docs are horrible)

What makes documentation good?

• Easy searchability - I should be able to navigate around your site without Googling every topic 
• Easy language (controversial) - Use language in a way that someone who is brand new would understand what you're saying. This is controversial because some topics are advanced and might suffer from using beginner language, so maybe this is best used on beginner topics (ie declaring variables in Svelte, Vue, React, etc.)
• Clear explanations with examples
• Code playgrounds - try on-page before you try in your code
• Proper article breaks - don't cram everything into one guide and don't put too little in there, write enough to solve a problem or concept and then divide those concepts up into individual guides so that they can be searched up more easily on Google and internal searches 
• Clear versioning - what version of the plugin does this refer to?
• Up-to-date info and screenshots 
  - Stick to default themes and layouts for screenshots wherever possible so that someone can revert their custom UI to default and follow along 
• Tell me where to put the changes (personal one)
  - I never know where to put the code snippets or changes to settings when im starting out and I always have to ask BingAI where 
• Tackle community problems - if there are a lot of support forum posts showing confusing on setting up a contact form's SMTP setting. Make a good piece of documentation covering it and maybe consider a feature refresh in the next version - with accompanying documentation

‍