About Documentation Being Hard

Documentation is hard. I know this from trying to document my Tyfy framework. Documentation must be a skill that some individuals are born with. Maybe it is honed through years of practice. Perhaps it requires a gifted teacher. I don’t think I have the necessary skill. I’m not a gifted teacher. I was never a very good writer — I gave fits to one of my high school English teachers.

I often encounter bad documentation. Okay, maybe not “bad” but difficult for me. The Drupal documentation is an example. I think poor documentation is one of the reasons why Drupal is not as popular as WordPress. Drupal documentation is a mix of incomplete and opaque. It requires the reader to have experience as a programmer. I’ve acquired a little of that experience, so maybe that’s why I think it’s gotten better. But it still has a lot of holes and rough patches. There are places where people clearly haven’t put in the time. I understand that documenting Drupal is volunteer work. But the problem limits the adoption and popularity of Drupal outside the hard-core enthusiasts. They have the technical wherewithal to power through difficult documentation.

The documentation for Eleventy got on my nerves today. First, the design is terrible. The font and color choices make parsing the documentation pages unnecessarily difficult. They need to take some cues from the Nunchucks documentation — a relative oasis of clarity. Eleventy is also new and simple. There are very few practical examples available. It’s not clear where it would be best to use Eleventy, a templating engine, or JavaScript to solve a technical problem. Something as simple as displaying the full text of the latest post on a page took an extraordinary amount of time to research. This seems like a pretty simple use case and my solution feels like a hack. I am left with the sense that Eleventy can get you up and running quickly if your needs are simple; beyond that, good luck. The documentation may or may not help you.

Good documentation takes time. I know I’ve rarely put in the requisite time and effort, so it’s hypocritical for me to ask others to do the same. But I know that others will be more likely to use the things I’ve built if I could provide good documentation. Likewise, everyone will be more happy to use tools like Drupal and Eleventy if the documentation were more accessible.