Living documentation for developers

At work we are storing all our technical documents (process descriptions, technical and functional documentations) in Confluence. For developers (and especially me) it is difficult to store technical documents separated from source code.

In the past I often got in trouble because the documentation for our current product was outdated and some adapted functionality, after a live deploy, did not work out as expected.

This led me to think about our current documentation update process, actually there was nothing defined in my team. So I started to think about how I am able to ensure an up to date documentation when the source code changes in confluence.

Luckily we are also using Jira for our ticket management, so I talked to our agile coach to spot all possibilities to not forget the documentation update when a ticket goes to production.

Manual update when a ticket goes live

There are several ways to get informed by Jira when a ticket goes to the done state. This would allow me to recognize when I need to do a documentation update for a certain functionality.

To be able to do so I suggested to introduce a new label called “needs-documentation” that would allow Jira to filter tickets I want to get informed about.

But in fact this solution is involing a manual step to do the documentation update and this felt awkward to me, so I started to examine possibilities to store the documentation (at least the source) nearby the actual source code and generate the confluence representation out of it.

Markdown to Confluence

After a short research on existing npm packages I found markdown2confluence which allows me to generate confluence markup out of normal markdown files.

But this generated markup also needs to be copied manually over to confluence what also annoys me.

So I continued my package search and found md2confluence which is actually a wrapper around markdown2confluence that includes also the uploading part to confluence.

Setting up md2confluence

To get started with md2confluence you basically need to install the npm package.

npm install --save-dev md2confluence

The second configuration step that is needed to complete the setup is to create the rc file (named .md2confluence-rc) with the needed configuration.

{
    "baseUrl": "CONFLUENCE_URL/rest/api",
    "user": "USERNAME",
    "pass": "PASSWORD",
    "pages": [
        {
            "pageid": "123456",
            "mdfile": "path/to/md/file",
            "title": "A sample page title"
        }
    ]
}

You need to simply replace all the uppercase placeholders with your actual configuration and define your pages to generate and you are good to go and start generating the content of your confluence pages.

Generating the confluence content is then started by typing:

node_modules/.bin/md2confluence

Conclusion

As you can see it is fairly simple to automate this annoying documentation step at the end of your ticket lifecycle. You do not need to do this step manually every time you change the behavior of your application.

A general advice in the end. If you plan to use md2confluence in multiple projects you could/should add the package as a global npm dependency.

When you include this tool in your development workflow you can automate your documentation update process but of course you need some mechanism to ensure that documentation updates actually happen. My advice is to introduce a ticket label (as already mentioned above) called needs-documentation to make the need for a documentation update visible to you and your team.