Defining an efficient documentation structure

Any type of project or application will always create a certain amount of documents & written information. This is not any different at Foreach. We have documentation spaces for several customers/applications/projects and recently we decided to have a more in-depth look at how we use them. The objective was to improve our documentation approach, as we felt we were having some issues left and right. In this article I try to describe the approach we took and the result that came out of it. But to understand where we're coming from it's probably best to give a bit more background on how we work.

How we work...

First of all, in case you did not know: we build software, mostly for the web and almost always made-to-measure for a specific customer. You could perhaps say we specialize in web platforms, which is our term for an application that needs to support several websites and usually has a great many integration points with different applications.

As a company we are organised in several cross-functional teams. We consider the team aspect to be pretty important and each team is responsible for one or more customers and several projects/applications. I mix the terms projects and applications because they often intersperse with each other and the line is not always clear after a while. In its most simple form things start with a single project to build something new, the project can be clearly defined having a start and end date (the initial release). Once the end result of the project - the application - goes live, we are more or less in maintenance mode on a running application... the project is finished.

This is where it often gets murky. Most of our services relate to fairly large web applications, where we:

• support the running application, handle customer requests (like reports) and perform actual maintenance (what we call operational support);

• push out new releases all the time with new features that have been developed without the context of a project or actual deadline;

• often have one or several larger development projects ongoing;

We try to attribute customer responsibility to a single team. In short that means that any team is usually busy with all of the above at the same time.

There is a lot of similarity between what different teams do and how they do it, something we try to stimulate as much as possible. However, smaller and larger differences are unavoidable. Things like technology stack, specific customer demands or type of application will always influence the way of working.

We do try to standardize to a healthy level, and as with - I assume - any company, we also want experience to circulate. Two ways we believe to be making this happen is by creating a collaborative culture and by very actively rotating team members. We rarely change the scope of responsibility of a particular team, but we do regularly swap members between teams. That's often both easier and even more beneficial than trying to change roles within the same team. To be able to do this without impacting teams in a negative way, it is very important that we make it as easy as possible and remove any overhead (like needing 3 weeks to come up to speed with how the other team works).

The problems we faced

When it comes to documentation and a collaborative culture, we chose Atlassian Confluence as our platform of choice a couple of years ago. This means we actively push this platform as the single place where everything should be documented, trying to avoid a mash-up of things like Sharepoint, network drives, printed documents, etc. And since we do not put heavy restrictions on alternatives, we want the Confluence space (our "intranet") at the very least to be the most reliable source that refers to any other sources. Anyone at Foreach can easily put stuff on Confluence, there's very little restrictions.

It is perhaps important to know that Confluence primarily uses a tree hierarchy to organize content; much like a folder structure on the file system. There are some other categorisation options (like tagging), but the hierarchical structure is most relevant in our case.

Now, over the years we have built up quite a variety of documentation for the various customers/projects/applications, and each team maintains its own set of information. We started feeling that we had a couple of issues that were hindering us in making effective use of the content we have:

• even though the different applications, projects and teams have a great many similarities, the documentation structures did not;

• different types of information were often interspersed with each other, which made it very hard to "see" the structure or to know if something exists or not;

• where content was put often depended more on who was creating it than on on what it was about;

• the only real way to find something was to do a Google like search, of course this implies that you know what you're looking for. While that is a very valid use case, the situation made it very difficult for a new team member to find the way around the documentation on his/her own. It also made it more difficult to provide operational support by people less up-to-date about the systems.

• a lot of information was outdated. Often due to the fact that is was project related and the project had long passed, but also because there was no way to effectively review existing documentation.

A big part of the solution for these problems lay in defining a common documentation structure that we could apply in most - if not all - cases, so we set out to define this structure.

The approach we took

First we envisioned what the ideal end result should be like. This resulted in a set of prerequisites:

1. It should be uniform and recognizable: a team member that switches teams should immediately find his/her way without needing extra explanation.

2. It should be lightweight in its use: it should not add overhead but limit it by answering the question "Where should I put this information?".

3. It should be extensible: it should serve as a fixed basis, but not impose any limitations beyond it.

4. It should be reliable: if a certain type of information is not available in the expected location, this should mean it simply does not exist.

5. It should facilitate the maintenance of the documentation it incorporates.

Next we defined a couple of specific questions we'd use to verify if the proposed solution works:

• If I'm a n ew member joining the team, how can I get started on a specific task for a particular application?

• If I'm an end user, where can I find information on how to do something?

• If I'm a team member, where should I put information like analysis, discussion topics, database diagrams, manuals, etc.

• If I'm management or any other stakeholder, where can I find information about the latest releases, upcoming features and the long-term pipeline?

• If I'm called for a technical support question (eg. site is down), how can I quickly find all the information necessary to be able to intervene?

In the end the sum of all requirements could be identified as:

1. matching all prerequisites

2. provide the answers to the verification questions

3. being able to convert all existing documentation into the new structure

Analysis of our current content

The existing documentation was the main guideline for coming up with the new structure. We had an in-depth look at all content available across all teams and projects, and decided to categorise them on 3 domains:

Target audience

Who is the content intended for? In our case we managed to identify 4 major groups:

• customer & end user

• functional/design/analyst user

• implementation/development user

• maintenance & support user

I want to point out here that the entire exercise solely resolved around the documentation for the operational teams. Business functions like administration, HR, business development and management were not taken into account as they would have an entirely different set of requirements and there was little or no urgency from their end.

Note also that we segmented purely on target audience, and did not take the original author in account. Both consumer and writer of the documentation are covered in the base requirements and verification questions, but only the former was actually used when designing the structure. It turned out the end result automatically was much easier from an author point of view as well.

Type of content

This is actually very closely related to the above, but we found it easier to treat them as 2 separate categories as they are sometimes not exactly the same. When it came to types of content, we ended up with the following 5 groups:

• end user documentation -> manuals, public API descriptions

• technical documentation -> architecture overview, class diagrams, database diagrams, technical how-to

• support documentation -> infrastructure information, contact information

• project related documentation -> designs, analyses, requirements

• general team documentation -> meeting notes, process descriptions, retrospective reports

On the target audience and type of content categories we noticed that a lot of content was just badly segmented. For example a single document would contain part user documentation, part technical documentation and part infrastructure.

Relation to time

Here we looked at the content and the relevancy of it "today". We could broadly divide it into 3 simple groups:

• this documentation is no longer really relevant -> perhaps it is completely obsolete, perhaps only to be kept for reference for historical purposes (like meeting notes)

• this documentation is not yet relevant or is relevant right now but not tomorrow -> this is mostly things like project documentation (technical/functional analysis) and unfinished documents

• this documentation is relevant right now and will remain relevant unless some undefined change happens

We noticed we had a lot of things in the "no longer relevant" and "unfinished" category.

The new structure should group content as much as possible according to the domain(s) it fits in, and the relevancy of the documentation "today" should be immediately obvious to the consumer.

A usable structure

Starting from all the documentation we had and having a much clearer view of what we wanted, we came up with the following end result:

Our documentation structure for applications

Home

00 - About
01 - Roadmap
02 - Development
01 - Process
02 - Getting started
03 - Frameworks & tools
04 - Conventions
05 - Technical documentation
03 - Work in progress
04 - Release notes
05 - Maintenance & Support
01 - Infrastructure
02 - Deploy guide
03 - Technical support
04 - Accounts
05 - Who's who
06 - User documentation

That's it, no more, no less. These are the only pages that are defined as "absolutes" in the new structure:

• they should contain a specific category of content;

• they should be named exactly so and should have this exact hierarchy and order;

• if one of them is not present it should mean the entire category it represents does not exist;

There are absolutely no limitations on the content below any of these pages, as long as the base structure above is adhered to.

The only reason for the numeric prefixes is to be able to use automatic alphabetical sorting instead of manually having to order the pages.

The names of the nodes are meant to be pretty self-explanatory, but without going into the sub-levels, let me explain the reasoning behind the first level pages beneath the landing page (Home):

00 - About

The general introduction of the application(s).

01 - Roadmap

All things related to planning and specifications. This is the main working area for the analysts and will contain things like backlogs, wishlists, functional specs for a future version etc. This is the main area where you will find the actual projects.

02 - Development

Groups everything that someone needs to know to be able to develop on the application. Note that a technical analysis for a specific story to be implemented does not belong here, a technical overview of how something is implemented does.

03 - Work in progress

As the name says, this contains all unfinished documentation and documentation related to features currently in development. It can be a fine line but in its most simple form this would contain all documents that are being worked on in the current development sprint. Documents relevant for upcoming sprints can be found under Roadmap. Good use of this area is crucial, as it avoids unfinished documents to clutter the already relevant documentation, and provides a good entry point for hooking the documentation to the development process.

04 - Release notes

Because we often have very frequent releases (every 2 weeks in many cases), this area gives an overview of the entire release history.

05 - Maintenance & Support

Groups all documentation relevant for operational (technical) support of the applications. Ideally this would be enough so a team member without knowledge of the inner workings can offer basic support (like restarting applications, check log files, etc).

06 - User documentation

Contains all end user documentation like manuals or public API's.

Looking back to our requirements and the analysis we did, we can clearly recognize target audience/content type (release notes, user documentation, development) and time aspects (roadmap, work in progress) in the end result. I leave it up to the interested reader to see if how much of the questions he or she can actually answer without a more detailed explanation of the structure

This layout is very clearly not meant for projects as such. It is meant for running applications that have (or might have again) active development and use. It provides placeholders to incorporate project specific documentation, but that is secondary to the day-to-day running operations.

How we put it to work

It is a basic requirement that every team member understands the layout. So we briefed all teams in detail and publicly documented the structure with an elaborate explanation.

When explaining this structure to the teams, it became obvious that the Roadmap and Work in progress nodes cause most confusion. It took some further clarification and discussion before most team members had a clear view of how to use these. However we are confident that a little experience will go a long way in clarifying for the future and at this point in time, it just did not make sense to try to define a more fixed structure. The basis is that common sense should rule.

There was also some debate among the teams if they should create a new document space with this structure for every single application. In the end it was decided to keep this optional and again go for the common sense approach. Some of the applications we maintain have so much in common they can share a lot of the same documentation, in which case a segmentation on a lower level would be much more pragmatic.

Some members of each team were involved in the phase of defining the structure. Before deciding upon a final proposal we did some proof of concepts by migrating smaller document spaces to the new structure. We deliberately left the bulk of the documentation as it is so the teams could migrate them to the new approach and as such familiarize with it.

Maintenance and reviewing of the documentation

An important step we must still incorporate is keeping all documentation up-to-date. This means we need to incorporate this in our development process. We believe we have made this easier now by centralizing unfinished and temporary documentation in a Work in progress area, where a periodic review (for example every 2 weeks when a development sprint ends) can help in keeping it in a pristine state. We hope that a regular case of "we need to get this out of WIP, where do we need to put which part?" will stimulate better segmentation of the content, and will also bring older content back into view. Of course a periodic review of the current documentation will still be required.

When it comes to obsolete documentation we have one simple rule: get it out of the way. It's not "throw it away" because not everyone wants to remove it, but it should get either moved to trash or moved to a special archive folder. An example of a form of archiving quickly came up in the roadmap section for example where one team immediately created a "Finished projects" node to hold all old project documentation.

And now?

All in all we are pretty satisfied with the result and have noticed that adoption of the new structure is easy. However perhaps the most important thing was the fact that we analysed our documentation and matched it to our needs, thus being able to come up with a central approach. Without a doubt we will still adapt the current structure over time and it will only be common sense to review it from time to time.

Our most important challenge today is now making documentation maintenance an integral part of our development process, without documenting any more than is really useful for our operations to run.