Readme.io is a web-based, online documentation authoring system, that is quickly becoming the go-to system for online help and for good reason. With nothing to install, it offers a simple interface that all members of your team can get up to speed with quickly and to start contributing content. In this short article, I’ll cover some of the pros and cons of Readme.io that I’ve experienced in using it on client projects.
Readme.io offers an online documentation system that is based on Markdown – a popular markup language that offers a simplistic, and less verbose way to write HTML. These two factors make it easy for anyone on the team to contribute, especially developers, who often use Markdown in other areas these days, such as on Github.
Readme.io’s simple user interface is joy to use, albeit a bit buggy at times. While you can simply jump right in and start writing Markdown, you can also drag and drop a small number of content controls such as sub headings, tables, images, and blocks for code samples. The code sample block is particularly cool as it can be set to a wide variety of languages for proper syntax coloring. You can also switch to “raw mode” at any time to modify the Markdown generated by these content controls, and can also add raw HTML for things like anchors if desired.
Using these facilities, you can generate two types of documentation: “reference” documentation which is for API references, typically in the popular three-column layout that is seen with a lot REST documentation, and “documentation” which is for more general content such as overviews, tutorials, and quick starts. In both cases you get a TOC on the left with up to two levels of topics, and in the case of “documentation”, an additional, more detailed TOC on the right to jump to individual sections.
Cross links are also very easy to do. Simply type “[“ and then the name of another topic, and Readme.io will autosuggest a topic for you. Or, you can highlight some text and use the hyperlink icon that appears to link to an external site. This makes linking topics very easy which can greatly help the reader to find additional information.
The tool of course is not perfect. The two main areas where it falls short are in its usage of screen space and performance. When writing “documentation” (i.e. general documentation), Readme.io only uses about 60% of the available screen width, which makes it impossible to handle content such as wide tables. And in terms of performance, I’ve found that pages with large volumes of content, especially long tables which result in a lot of Markdown, Readme.io can take a long time to render and cause the browser to become unresponsive. Of course, neither of these issues are show stoppers and can easily be worked around with some clever content reorganization, but they’re both areas that need improvement.
Overall however, it’s an excellent tool that I recommend you check out, especially since everyone on your team can use it, not just the technical writing department.