How is the documentation structured at Wonderful

The challenges we faced

When working as a team, members need to share knowledge to be effective in their work.

Wonderful is of course no exception to this, and it’s even more true and difficult given the fact that our web production team evolves all the time (its composition varies with each project).

It quickly became clear that we needed to get more organized and efficient in the way we share information between all of us.

This context gives us several challenges :

• We have to onboard and train new colleagues or partners often.
• Some of our team members have some very specific skills, which leads to other people always turning to them for answers on those specific subjects. It created a state of dependency.
• Our team is composed of different profile types, and for those types, we have collaborators with different skill levels, different backgrounds, and different points of view.
• The team is becoming more and more remote and asynchronous over time.
• The team has adopted a continuous improvement strategy, which means we analyze and adapt our processes frequently, and we need to pass the changed information to everyone.

Content

Those challenges shaped the way we organize our web production documentation in many ways. I’ll try to go over each of them.

Procedures and How-Tos,

We started small, by simply putting in common notes each member kept on his/her machine. The interesting thing with this is that it makes you realize that even non-redacted bullet points can have an impact on the team. Starting small worked for us.

We’ve witnessed situations, where we started a file with 4 simple bullet points in it, then someone would add more precisions, then turn bullet points into sentences, then add 2 more points, and so on until we realized that thanks to continuous improvements, we had created a proven and tested procedure on this specific subject for the company.

Still improving on this approach, we’ve turned some repeatable or long procedures into automated scripts any team member can run. For example, we turned the procedure to create a new website into a scripted assistant that automates most of the tasks for us.

Grouping by profiles

The second thing we did, was to organize the doc content via profiles matching the ones in our team. (Integrator, Frontend Dev, Backend Dev, Lead Dev, Webmaster, Product Owner, etc).
This content organization helped us a lot in training new members.

If you have a new person, whose profile matches the ones already documented, it’s easier to onboard and train the person on notes that are specifically tailored for a similar position in the company. You can then gradually expand the person’s horizon on other profile types.

Another positive effect this content organization had, was to reduce the dependency we noted earlier. People now had another way of finding relevant information instead of asking the reference person every so often. Our team gained autonomy, and as a consequence, it helped us reduce the company’s bus factor.

The third thing we noticed with the content, is that when working with people who have different backgrounds and different skill levels, the fact to make them all contribute to the documentation is very virtuous. People tend to nurture the doc while the doc nurtures them back.

Finally, we’ve built over time, sections regarding profiles we do not have within the agency, such as DevOps for example. This way, we don’t forget important procedures or how to realize them, even though we do not have a reference person internally. It also gives confidence to less skilled team members that if they follow the procedure, the outcome should be fine in the end.

Processes

Next to profile specific documentation items, we created a “Processes” part.

In this part of the documentation, we try to write down the current state of Processes that are active at the moment within the agency. We’ve done this because we try to improve the way we work after every finished project, and this way of working generates a lot of changes. By keeping our processes up to date in the dedicated doc section, we ensure to have a source of truth, a reference to go back to when trying to remember how to organize something, which is very handy for training a new person too.

Currently, our processes are organized in 1O chapters :

Web Shaker, Budget, Web design, Backlog, Project generation, Dev, Recettage, Post Mortems, and Maintenance.

Technology

It’s not that easy to choose a documentation tool. We’ve chosen daux.io five years ago. I won’t write too much about why and how we’ve chosen this specific tool as this is a bit off-topic. If you’d like to get some insights about this, I’ve covered a specific chapter about choosing a documentation tool, then organizing its content in my software productivity course.

Building the doc

Daux.io is a PHP and markup-based documentation tool. More precisely, here’s how it works :

• You install it via composer.
• Then you create your documentation content via some markdown files and folders.
• Then you launch a terminal command which will generate the static HTML documentation files out of your markdown ones.

Hosting the doc

We aimed to make the documentation available to our wonderful colleagues and partners, so we had to deploy and host the documentation files somewhere.

First, we created a GitHub repository to host the markdown files, then we set up a Jenkins CI job to generate and deploy the HTML files. This way, the documentation benefits from every source control advantage (shareability, source files integrity, git-flow mechanisms, web hooks). The person updating the doc just has to commit and push a change to the repo, and the rest is all automated.

Once Jenkins is done with the file generation and deployment, it sends us a slack message to notify us that the online documentation is now up to date with the latest changes.

Our documentation content is not really sensitive, but we still protect it. It is hosted online privately, only accessible via a VPN. We create personal access for external partners.

Conclusion

Our documentation holds a great place within our team. It helps us centralize our knowledge while making sure we rely less on specific colleagues which reduces our company bus factor. It allows us to make some of our communication asynchronous, by stating processes or anticipating the training phase. It’s been positively adopted by our internal and external team members. It’s often overlooked, but it’s a powerful tool, that added some significant value to the way our team operates.