Word processors spell trouble for your project documentation
Modern day word processors are as ubiquitous as sliced bread. People use them for everything from writing a receipt to a business plan. However these editors are also probably the worst choice when writing documentation. Before you call me crazy or seek to send me a politely worded note online, think about the last project you used a word processor like Microsoft Word to write the documentation. Do any of the scenarios below sound familiar?
Typical documentation issues
- Keeping documentation up to date: The team finishes the application and proudly delivers the related documentation. All is great in the world. Three releases later, a user opens the documentation and not even the screenshots match the application. This scenario is so frequent, the running joke is that the documentation is obsolete the moment it is written.
- Determining which version of the documentation to use: The team updates and publishes all documents. However, someone notices that the new version does not include the latest changes and may in fact have reverted to an older version in some areas. The team realizes some members used v3 of the documents for their updates while others used the newer v4.
- Keeping track of the documentation master copy: Documents that have more than one author sooner or later end up with multiple master copies. As people email documents, it is easy to loose track about who has the master. It is all fun and games until someone ends up drinking a few gallons of coffee at two AM, merging multiple documents and hoping that nobody notices how he skipped a whole section.
- The documentation graveyard: It is unfortunately very common to be tasked to update an application just to find out all the documentation exists in an unmarked grave somewhere in a documentation graveyard on a corporate hard drive somewhere. When the documentation is eventually found (if it is found at all), trying to go through it feels like being Indiana Jones in the Temple of Doom. There are mummified code blocks chasing you, poisonous screenshot darts and overall evil forgotten library references that really make the hairs in the back of your hair stand. On the plus side, you get to feel like Indiana Jones, so I guess it is not all bad.
- Formatting hell: This is a typical scenario when trying to edit someone else's document. Surprisingly, the moment you add a simple bullet point, the formatting on the whole page just breaks. Little did you know the original author was a triple document processor black belt with a masters in nested tables. You hunker down, put on your helmet and hope for the best as you wade into the abyss of formatting hell.
How word processors enable bad behaviors
You are probably thinking: what does that have to do with word processors, these are all just bad processes. And you would be partially right, these are consequences of bad processes but the root cause is using the wrong tool for the job. While word processors are great for many tasks, they are not good for projects because:
- They are meant to be used to write single documents: You write a document save it and move on to the next one. There is no real concept of these documents being part of a project.
- They help us write shareable documents. These documents are expected to be easy to share and email. Unfortunately, this means that very quickly there is no single source of truth.
- They provide no real way to track changes. Yes, it is true that word processors have document change tracking. But, it is way too easy to accept all changes, disable the tracking or even copy the document . At that point all history is lost.
- They allow us to store files anywhere. Users can store documents anywhere they want, and I mean anywhere: Laptop, server, usb drive, google drive. Finding the right files becomes...well...a bit of a challenge, if you find them at all.
- They provide endless set of features. These features are meant to make documents look great. However, does documentation need to look like a tribute to Michelangelo and his Sistine chapel? Not really. While they should look professional, they do not need to have flashy formatting. More importantly, the team maintaining the documents nowadays is the same team doing development on the project and does not have the time for endless formatting matches. They need a simple tool to write documentation as fast and accurately as possible.
A Better way to handle documentation
Interestingly, these problems are the same problems that the software community solved to track the code for applications. Nowadays, code is located in a centralized location, all changes are tracked, there is one source of the truth, code editors have been optimized to maximize the developer's time and tools have been created to simplify the formatting. Can we apply those learnings to the documentation process?
This is where a new breed of text editors fits. They use a simplified text based toolset called Markdown to treat documents as if they were code files. The concept is simple: The author uses simple text to write content, character combinations to denote formatting cues and then have the editor automatically transform them into the correct visual formatting on demand. For example:, an author could simply type the '-' character to indicate an unordered list item (bullet point) . This and other examples can be seen in the table below and the markdown guide is a good reference for the full markdown syntax
| Desired Formatting | Markdown | Generated formatted Text |
|---|---|---|
| Bullet point | - list item |
|
| Bold text | **bold** | bold |
| Link | [Bolbeck](Bolbeck.com) | Bolbeck |
| Heading 2 | ## Heading 2 | Heading 2 |
The benefits of Markdown come from the fact that everything is plain text in the file, without all the extra hidden information that word processors put in the file. This means that:
- Documents can be tracked in the same change tracking system as the application code
- User can focus on writing and let the system deal with the visual formatting
- Single official source of the documentation is stored in the centralized management system
- All changes are tracked in history all the way down to the individual change
- Most markdown editors enablefast, accurate writing. Additionally, most modern code editors support markdown allowing seamless switching between code and documentation.
- Documentation is versioned alongside the code making it simple to determine if the documentation has been updated with the latest code changes. It also simplifies the creation of release notes as every time a change is made to a document, a comment must be made in the central repository about the nature of the change.
- Easy conversion of markdown content into all major formats like .doc or .pdf for external distribution is supported by most markdown editors.
While markdown is not the only text mark up solution ( AsciiDoc is another one for example), it is the de facto industry standard. In fact, there are a number of popular Markdown editors like:
It is also supported by popular code editors like Visual Studio code , Atom and Pycharm