Tools for Creating a Drupal Website Documentation

Whether you’re a freelancer or a contract programmer, we all face the same problem when we start working on an existing project for a client: how to quickly and (if possible) painlessly familiarise ourselves with the existing structure and code. Probably every one of us at least once in their career has asked with hope: Do we have any documentation here?

If you can't explain it simply, you don't understand it well enough. (Albert Einstein)

Importance of project documentation

Documentation is part of the product, its invaluable supplement, and a guide – for the programmer, the manager, the product owner, and the end user. A well-structured and well-written documentation is a win-win. On the one hand, you minimise the scope of the issues that the client will ask you about, and on the other – you make it easier for the people who will join your team or who will take over the system support after you. Therefore, having and (which is especially important) maintaining the most up-to-date documentation is an investment and a strategic move, especially in large projects.

If it isn't documented, it doesn't exist. (Sitepoint, A Guide to Writing Your First Software Documentation)

Types of project documentation

At the highest level of generalisation, we can divide the project documentation into the system documentation and the end user documentation.

The first type of materials will be of particular interest to developers, the second – most often to the client and the end user (the Internet user). However, how to deal with explaining all the intricacies and specifics of a given project, how to best document the processes taking place in the back-end, and how to dispel the users' doubts in a visual-based and simple way? To the rescue comes a whole range of tools, which with their functionalities will help you answer these questions, as well as create your website documentation.

Book-like documentation

One of the commonly used forms of collecting documentation is creating hierarchic content with chapters and subsections – just like in a book, i.e., a paper version of the instructions for users that comes with every product.

There are several tools for creating such a content structure. They all have built-in text editors that allow you to easily add a code fragment, lists, tables, and media attachments.

Confluence

Confluence is one of the Atlassian company's more enjoyable and powerful tools. The creators themselves describe it as a friendly place where knowledge and cooperation meet. Everyday work with this tool proves it to be true. We’re already used to wiki pages' structure, so even non-technical people can navigate and add content in Confluence.

After a few simple steps (especially if you already use other Atlassian products) you get a personalised website with the possibility of creating multiple areas (e.g., for several product versions) within which pages with articles can be created. You have an extensive tutorial and several dozen content templates at your disposal. The creation of your "book" is facilitated by the possibility of free dragging and deciding on the order and location of the added subpages, as well as the possibility of tagging, liking, commenting, and marking them. The tool is visually clear and legible. In addition, the free version provides 2GB of space at your disposal, and you can invite up to ten people to cooperate. Confluence is worth trying, especially if you keep your code in the Bitbucket repository and distribute tasks using Jira Software.

GitHub Pages and GitLab Wiki

If you like to keep your documentation close to your code, the ideal solution are the wiki features offered by hosting websites created for this exact purpose. Sure, you don’t have article templates at your disposal here, but the entered content is always at hand – right next to the repository, tasks, or new code implementation processes. The content organisation is similar to the previously mentioned Confluence. Gitlab even allows you to import the existing documentation from this tool. Individual articles can be grouped by indicating the path in the directory tree of your chapters. When adding content, you have at your disposal a simple editor that supports such formats as Markdown, Rdoc, AsciiDoc, reStructuredText or Org, and the publication process itself is carried out by adding another code package (commit message). Github Pages also comes with default skins that will make your documentation page look professional.

Camunda Modeler and Process Street

If the Workflows module is the centre around which the functioning of the entire website revolves, then for the understanding of all dependencies and processes taking place on the website (e.g. how the process of taking a loan, applying for funding, booking a visit, etc. is being carried out) such tools like Camunda Modeler or Process Street will prove to be an invaluable help. They are useful both in planning the processes and in documenting them. The main purpose of these tools is to support Business Process Management (BPM) and (in the case of Camunda) to create Decision Model and Notation (DMN) trees.

In short, if there are any recurring processes on your website worth documenting, you can do so with these tools. You will be able to create documents containing procedures or launch processes for your colleagues in mere seconds. Process Street is used when implementing new solutions or publishing new versions of the system.

While management will be delighted with the Process Street's capabilities, developers and business analysts will be more likely to use Camunda Modeller. The program works with all operating systems and functions as a cloud. It allows you to accurately reflect all the processes and connections between servers. There is also a designated place for collecting all the necessary information that a developer may need: server addresses, the format of the queries sent and the received responses, along with parameters, etc. The whole thing is very clear and intuitive.

Code-like documentation

It is time to move on to the solutions that warm the hearts of the most die-hard programmers – documentation in code! From the perspective of a new team member in a large project for a client, documentation as part of the code is the perfect solution. The culture of technical documentation as we understand it today was started in 2014 by the Twitter employees who took a step further from the commonly-accepted pattern – a developer writes the code, let them write the documentation too – and stated that they should write the documentation just like the code. The docs as code approach exceeded all expectations. We’re talking here about writing the documentation in the same place as the code – using exactly the same publishing process as when adding the code: commit, pull request, build. Comments in the code already favoured this approach earlier.

ReadMe.md!

Surely, everyone must have come across a file called README.md. Perhaps it was written as a plain text file or in one of the so-called lightweight text formats. It contains basic information on the project, on how to set up its development version locally, on who created and maintains it, etc.

You can go one step further, however, and create all project documentation this way. To do this, however, it’s worth using one of the available formats, which transforms the simplified version of the text into formatted text that is easy to read for the user. One of the most commonly used formats are Markdown and reStructuredText.

Build your documentation

What if you could automate the entire process based on the comments on the existing code, and at the same time – create a kind of documentation-book that will update itself with every change in the code? Of course, nothing can replace human contribution to the creation of project documentation, but the option to obtain its framework, its main outline automatically, sounds encouraging.

There are many such generators, and among these the most useful for Drupal users will be obviously the ones based on the PHP code. Worth recommending here are:

• ApiGen – creates clean API documentation on the basis of PHP source code.
• Dexy – one of the most versatile generators, it supports several programming languages, as well as input and output formats.
• docgenerator – allows you to organise the documentation in the form of Markdown files.
• DocumentUp – for GitHub code owners, it allows you to improve the documentation created using the Markdown format.
• Doxygen – supports many programming languages, generates the documentation online (HTML) or as a manual in LateX or other text formats (PDF, MS Word).
• phpDocumentor – one of the first of its kind, allows you to create class diagrams in UML, supports the latest PHP version, offers a wide range of help, and has many years of experience.
• PhpDox is not limited to API documentation. The collected information is being stored in the XML files that can be freely modified and then generated as HTML files.

Use Drupal for project documentation

In our Drupal agency, we decided to use Drupal to create documentation for the company's internal use. The basic version of a Drupal website is easy to set up and comes with default content types that are enough to get you started. We don’t even need to learn anything new – we’re Drupal specialists, after all! In our case, we also enabled the "Book" module. The added pages create collections related to each other – just like in the case of an actual book.

The main documentation view consists of two parts: on the left side, there is a block with the content tree, on the right side, the content of the selected chapter is loaded. Each page is added as a separate node, we use the default CKEditor to create/edit the content. It’s enhanced with an additional CodeSnippet plugin. We’ve added our corporate colours to everything and… voilà! The content is being moderated by both – developers and non-technical people. It stores content ranging from typical HR-related issues to local project development. Our new employees receive a ready-made repository of knowledge on how to navigate all company issues and how to start the work on the assigned project.

Summary

There are many tools to help you create and, more importantly, maintain up-to-date documentation. Which of them to choose depends on your project's specifics – its size, number and the type of modules used. It’s also influenced by whether the website is mostly static or process-based, who will create and use the documentation, whether you want to share it and many, many more factors. However, the fact that the documentation is part of the product and has an economic value – as it allows to reduce the costs (i.e., the developer's hours to familiarise themselves with everything) – will remain. Good documentation also helps to attract clients (as we’ve already quoted – "if it isn't documented, it doesn't exist" ;)) Go for it then!