Documentation as Part of the Software
There are various ways to document software. For developers working in an IDE, it is most convenient when the information they need is available straight away. Therefore, I want to argue in favor of an approach which makes the documentation an integral part of the software.
Some months ago our CTO Fabian Wesner wrote about the importance of a Clean Documentation and explained in which ways information should be presented. Besides stressing the importance of clean code, he describes a wiki-based documentation as one possibility to gather all the information required for your project. But I think especially regarding the documentation of code, a wiki often is not the best choice. A lot of developers spend most of their time working within an IDE like PHPStorm. In case they need to obtain specific information contained in the documentation, they need to access the wiki. Why not avoid this context switch by making the information available where it’s needed; i.e. directly within the IDE?
Readme
Even though, the concept of readme files is one of the oldest ways to document important information, it’s often ignored. This, most of the time, is due to an overload of information contained in the readme. Ideally, it should only contain important information, e.g. instructions on how to get started with the code, information on where to find different parts of the documentation, and it might answer common questions like “What’s important to run the software?”. By providing this kind of information, a readme file serves its original purpose. But since readmes are part of the software and can easily be accessed without leaving the IDE, they’re good candidates for the documentation of code. So why not take this concept to the next level?
A good example of this kind is the FOSHttpCache repository. Besides the src it contains a doc folder which includes all necessary parts to document the installation, configuration, usage, and development of the bundle. This enables you to dive into the documentation when you need to, without having to search for it.
Documentation Is Mainly Code
Another good reason to make the documentation part of the software is that it mainly contains code, even if it’s only human readable. So instead of having to fight against editing permissions to change wiki sites which document how to use certain parameters, you can simply change the documentation inside your repository. This makes it as easy as possible, even for new project members, to edit the documentation in order to fix mistakes or to update parts which are no longer up to date.
Markdown vs. reStructuredText
There are two common documentation languages, which both come with specific capabilities. The simpler one is Markdown. It enables you to easily write a documentation that includes formatting information. Markdown turns out to be especially useful in combination with GitHub, which renders Markdown files by default and displays a rendered preview. All major code hosting services feature a similar preview. But GitHub’s flavored markdown offers a better syntax highlighting for many languages, tables, task lists, user mentions (which link to the user’s profile on GitHub), and emoticons. A good way to get started with Markdown is Mastering Markdown.
The second common language used for documentation purposes is reStructuredText. Except for its markup syntax it’s not so different from Markdown. It is mainly distinguished from Markdown by better tools for post-processing. The Sphinx project, for example, offers the possibility to render reStructuredText into different formats. Even though this can also be achieved using Markdown, there aren’t as many good tools for rendering Markdown. Sphinx enables you to render reStructuredText into browsable and searchable documentations or fully styled, printable PDFs, for example for user manuals.
So which language should you prefer? In my opinion, Markdown is easier to start with, but reStructuredText offers more possibilities regarding post-processing. So the choice is up to you.
Diagrams
No matter what language you chose, the most important role of a documentation is to convey information. In certain cases, for example, when you have to document complex structures or an overall architecture, a diagram often turns out to be way more useful than a hundred lines of text. As Fabian wrote, we’re currently using the gliffy plugin for Confluence to include diagrams in our documentation. This is fine but only for Confluence users.
In general, there are a lot of good tools to create diagrams. The main problem is that everybody uses a different one. A way to circumvent this problem is to use PlantUML, which delivers a simple and intuitive language to create diagrams and can easily be integrated in many tools. Sure, writing code to compile diagrams isn’t as convenient as a visual, clickable tool, but it avoids compatibility issues beforehand.
For PHPStorm, for example, there is a plugin dedicated to PlantUML integration, which allows you to compile and save diagrams. This makes it easy to create UML-like diagrams and to include them in your documentation. Another advantage is that you are able to share and easily edit the source code of each diagram.
Conclusion
I strongly believe that code related documentation should be an integral part of the respective software. This way it can easily be accessed and edited. Furthermore it can be included in your source control system and thereby evolve as your code does. This way you even have a history of your documentation.
