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.
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.