Many software companies give their technical writers the responsibility for creating a documentation strategy. While it can work well at times, it often ends in a huge mess. Even where the technical writers are well up to the challenge – many are – they frequently don’t get the backup they desperately need.
30 years ago, it was the stuff of science fiction. These days, we take the idea of talking to chatbots fairly calmly. But we often forget to think about them in terms of documentation.
There’s no point documenting our software if people can’t access the resulting information. That’s why we should be careful to always create accessible documentation.
A knowledge base can be an awesome resource or an appalling waste of space. The difference often comes down to its design. Consider these key points before you start to write content.
Once you’ve done your planning and have your directory structure figured out, the next step is to start creating your project. You’ll need to create your base directory, use sphinx-quickstart to set up your basic project structure and configuration, and then – if needed – add some extra structure.
Most software companies I know are still pumping out user guides with great enthusiasm. When a client approaches me about a product, they’re almost always talking about creating paper or PDF manuals. But are we reaching the end of the user guide life cycle?
Lots of companies hire a technical writer when they need a documentation consultant. The results are often a stressed tech writer, a dissatisfied customer base, and a vague feeling that there must be a better way.
The source directory structure that you choose will end up embedded in a lot of documents. That includes configuration files and every single internal hyperlink created. It’s possible to go back through and change things later, but it’s also a pain in the neck.
I’ve attended technical writers’ meetings that were focused on new forms of documentation, new methodologies, how to push the documentation agenda for a piece of software, how to get people to read the user manuals… there’s a lot of focus on good documentation, which is great! Except… there usually isn’t much focus on useful documentation.