Creating Manuals Using RST and Sphinx: Base Documents
In Sphinx project, ‘base documents’ are like the skeleton of a manual. In a table of contents, they’ll show up as the chapter headings.
In Sphinx project, ‘base documents’ are like the skeleton of a manual. In a table of contents, they’ll show up as the chapter headings.
Agile documentation isn’t that hard once you get your head around applying software development methodology and concepts to technical writing. Here are a few tips for making your documentation truly agile.
A master file controls almost all of the content that will be included in your user manual. It contains a list of your base documents and specifies what your table of contents will look like.
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?