Fixing the State of Technical Documentation
Technical documentation has long been an uncomfortable element of free/libre software. Improving documentation is a topic that needs discussion.
I agree with the points made by a recent writer. A few points are missing.
- Rapid release.
- A lack of a rich text format interface.
- Complicated revision control.
- A presumption of a 24/7 Internet connection.
- A presumption of using IRC or forums to obtain help.
Rapid Release
Rapid release models do not lend well to volunteers maintaining documentation. People have busy lives. When committed to a free/libre software project, volunteers need time to digest and understand software changes to support the documentation. Rapid release does not allow non geeks time to breath.
A Rich Text Format Interface
Many professional tech writers use Microsoft Word and Adobe FrameMaker. There are tools to create chm help files. Even when there is some kind of revision control system in place, the daily interface is rich text formatting. In the free/libre software world, nobody uses a rich text format tool. Non coders and less tech savvy people who want to contribute to projects by helping with documentation are expected to become geeks and learn geek tools and some kind of markup or markdown language.
LibreOffice Writer could be such a front-end for documentation projects. A template with predefined style tags would avoid formatting issues and just let people write.
Another possibility is something like Lyx. Although primarily a front-end to LaTeX, Lyx or a similar tool would provide a familiar rich text format environment and allow writers to focus on content and not worry about the final output.
Complicated Revision Control
A majority of people who would like to contribute to free/libre projects through documentation are, first and foremost, users and often not geeks. Such people cannot and should not be expected to master revision control schemes such as git or subversion. Such users need a simple point-and-click method to submit changes. That might mean somebody else reviews and approves submissions.
A Presumption of a 24/7 Internet Connection
Many free/libre developers choose a lazy way of avoiding documentation by only providing their documentation on web sites. The least they could do is package the web site contents into /usr/doc along with a respective *.desktop file to open the web page in a web browser so users do not need to be online to read the documentation.
Wiki developers have completely missed the point with usability and wikis remain the domain of geeks.
IRC and Forums
Non technical users don’t seek help this way. If there are no respective help files, they grab their phone and ask a computer person for help. Thinking that non technical users will use IRC and forums is a pipe dream.
Posted: Category: Commentary, Usability Tagged: Tech Writing