This is the sixth article in a seven-part series of blogs that describe our most recent changes to the architecture and content of our documentation. We focus here on the challenges of taking on such an ambitious undertaking. 

Redesigning our docs took nearly one year to complete, with close to twenty people working on it. We took our time, planned carefully, created a collaborative and engaging work environment, and anticipated the impact on our contributors and customers. All of this played a role in delivering our new docs.

And the first step? Knowing when to take the first step.

Waiting for the right moment

Let’s go back one year before the project began. We already knew we needed a change, but we were only two on the doc team—one tech writer and one back-end developer. It would have been impossible. This kind of big revamp needed time and more hands on deck. It had to be done at the right moment.

But this didn’t stop us from doing some preliminary work to move us closer to our goal. In parallel to our usual day-to-day activity of maintaining our documentation, we also took small steps to lay the groundwork to a full-scale architectural change,  For example, we started to restructure our how-to and tutorial pages, having in mind that at one point we’ll want this content to be easily accessible from our guides.

When our team grew from 2 to 5, and outside contributors were ready to go, and our backlog of tasks-in-waiting for the redesign reached orange alert—we decided to start the project.

Planning

What can be easily underestimated when doing such a big revamp is the planning phase. The full project took us 9 months to complete but the actual work—rewriting the content and coding the new UI – took us only 3 months.

That left us 6 months of upfront design. This might seem crazy but it was required in our case. Let’s take a look at why.

Writing down a first vision

You need every member of the docs team to be aligned. You also need the other contributing teams to understand the context in which they will add their work. Finally you need to explain more globally why you’re doing such a big revamp. For that you need to have something in writing.

This vision needs to be a shared effort between all contributing  teams, so that everyone feels involved in the project and understands their impact. If you are not doing that for a project of this size, there is a high chance people won’t want to work on it or will get discouraged quickly.

Iterating on the vision with user research

As explained in parts two and three of this series, we conducted extensive user research that allowed us to validate our vision and make better decisions.

Also during this time, we iterated on what we wanted the experience to be—designing the information flow, bootstrapping the pages, and outlining the content.

This was also a good time to think ahead, to anticipate potential issues. We slowed down the process by spending several months on the design alone. This not only helped us to align, but it ensured that everyone would have the big picture of what we were trying to achieve. The more we moved forward, the more we involved other Algolians for advice and opinion. This created a mindset where a lot of people in the company were aware of the project and supported us in the process.

Planning for production

Once we knew exactly what we needed to do, we moved to planning. We all agreed that it would be better not to spread the work over too long a period of time, so we time-boxed it to a single quarter. We split the work between what was necessary for the release and what could be done in later iterations.

The amount of work required was huge and the number of people needed for contributions was huge as well. We took a week-by-week approach, where we sprinkled the different tasks over the full 3-month target period. This kind of planning impacted all of the contributors and played a critical role in managing dependencies and deadlines.

Splitting the project into smaller sub-projects

Every team would not participate in all parts of the project. Aligning the different parts was therefore important to the overall goal. Just knowing the end goal was not enough; every team needed to know precisely the scope of their responsibilities.

Here’s how we split the work:

• Research (Design + Docs team)
• Rewrites of guides, tutorials, and how-to pages (Docs team)
• Code snippets for guides in all languages (Docs team, API Client team)
• Web (InstantSearch web team)
• Mobile (InstantSearch mobile team)
• Widget showcase (Design + Docs team)
• Redesign (Design + Docs team)

This was just a first split. By doing this, we were able to know which team was responsible for which part. Depending on the team and the sub-project it was sometimes necessary to split the work even more, enumerating individual responsibilities. Some teams did this split on their own (verbally) and that was sufficient. Other teams needed to write down the individual tasks.

How Formal should the process be?

My advice is to put in place a formal process only when needed. If a team is able to and wants to organize itself better, give them that autonomy and flexibility. But if things go wrong, you need to react quickly and put in processes to get back on track. This can be done in several ways:

• More detailed planning.
• Alignment Meetings.

This is project management. We sometimes as a startup want to do things without process, without planning; however, for a large project, this is just not possible. From my experience at Algolia, as soon as you have more than 4 or 5 people working on the same project, you need a plan.

Managing Externalities

At Algolia we have a documentation team, but everyone is able to contribute to the docs, fix issues, update content. A lot of people contribute to our docs, developers as well as non-developers. Our support team members are also big contributors. So we needed to make sure that this project did not interrupt these important forms of contributions.

Mitigating Impact on documentation contributions

Prior to the redesign, our docs were composed of several parts:

• Guides
• Tutorials
• API clients
• REST APIs
• Frameworks integrations

Only the first two parts (Guides and tutorials) were going to be impacted by our revamp. Us redoing two parts should not impact the work of these people. So we decided that for as long a possible we wanted:

• To always allow contributions.
• To be able to deploy these contributions to production,

Modifying our repo

Our website codebase and content are hosted on a single private github repo: algolia/doc.

If we schematize the structure of the repo it would look something like this:

/doc
/guides
/tutorials
/api-reference

We knew that the redesign would change this basic structure.  We therefore introduced a new folder doc2/ that was not deployed in production but available in development mode, which we could preview in our github Pull Requests.

/doc2
  /guides
    /tutorials
    /how-to
    /in-depth
/doc
  /guides
  /tutorials
  /api-reference

This allowed us to work on the new content, without impacting the current docs.

We were also able to fix things and add new features on the soon-to-be-removed parts and deploy them to production in parallel.

There was one downside to this approach. For any change or fix that we did under /doc/guides or /doc/tutorials, we needed to integrate it somewhere into the new content. This can be easy if you have only a few people contributing, but in our case, with so many contributors, it was a challenge. What saved us was the fact that the docs team were the ones approving and merging changes to the repo. The docs team therefore was able to take full responsibility of making sure the duplication choices were done well.

We took a similar approach for working on our new design. We duplicated templates, layouts, and stylesheets.

Freezing deployment (but not contribution)

When we arrived at the end of the project, we knew we had to freeze deployment in order to finalize everything and remove the old content. Doing such a freeze impacted the full company, so we needed to plan it in advance and communicate our timeline. There are a few recommendations I would give when doing such things.

• Communicate early.
• Give people time to push things before the freeze starts to avoid issues and potential frustration.
• Tell people when the freeze is going to end.
• Before freezing, make sure everybody involved in the deployment is clear on their role and has dedicated time to work on it (because the freeze is not something you want to extend). More on that later.
• Communicate again when you’re done.

Freezing deployment did not stop contributions. Everyone was still able to contribute. This is important. The success of our documentation relies on our contributors. If you start telling motivated contributors to stop pushing changes, you threaten to lose their reflex in doing so.

Impact on our customers

We knew that restructuring the docs was going to require our audience to change their habits. Worse, some customers who were currently implementing their first solution were going to be shocked and get lost in the information shuffle.

As much as possible we wanted to reduce this potential friction. What we decided was to continue to make available the old version of the docs . We did this for one month to ease the transition.

We realized later that we could have done better. We could have done the inverse: keep the old docs for a month, but add a banner “try the new docs”. This would have allowed customers to know that something was going to change and to let them adapt to the new design at their own pace. Doing this could also have given us an opportunity to get early feedback from our customers.

Role of the Engineering and Product Managers

At Algolia, each team has one product manager and one engineering manager. One of their missions is to ensure that everyone is aligned. These two persons need to drive the project and make sure it gets completed in a reasonable amount of time. A lot of what we did to lead the project was based on instinct, and so very unique to the context. But there are some techniques worth mentioning that could be applied to other projects.

Dedicated time to work together

At some key moment, we decided to group everyone together in a room. For many developers, writing documentation and code snippets is not very enjoyable, and so doing these tasks together is far better than doing it alone.

This also helps with managing time. Every team has their own priorities, so aligning different teams can be challenging. By booking time in advance for all involved, we managed to have everyone working on key parts of the project and create momentum.

Don’t add time, reduce scope

For a big project like this, you don’t want to plan for three months of work and in the end extend that to six months. The strategy that we decided to follow therefore was to reduce scope instead of extend time. As soon as we saw something that would take too long and could delay the release, we asked ourselves the following questions:

• Is everything in this task needed for the release?
• Can we do a big part fast and save the rest for a later iteration?

In most situations, we were able to find compromises that allowed us to ship one part faster, with a bit less features or content. This kind of re-scoping put us back on track.

Ensure focus

When there are a lot of things to do, you want everyone to focus only on what they need to. Nothing more, nothing less. Every person needs to be accountable for their part. As soon as you have overlaps you are losing time and potentially delaying the product. When you are in “production mode”, this is not something you can do, you need somebody to have the overview. For us it was the PM and engineering manager.

Get your hands dirty

Once the team is in building mode, you don’t want to change their focus. So you need to help on all the small tasks for the team. Handling support, fixing small issues, reviewing the work, coding small features that would allow the team to focus on bigger tasks. Be available, on hand.

You also want to make sure that if there is anything you can do to increase focus, you should do that. This can be done by:

• Creating a script for a task.
• Putting in place a process.
• Unlocking discussions/decisions.

Make Decisions

Finally, making a decision on something takes up brain time. If you have to focus on a task, you don’t want to have to think about making decisions for anything other than the topic you are currently working on. Our goal as managers was to make sure that we freed up time by being accountable on all tasks and teams, by involving the necessary person for each. This can only work if the teams trust you to make the right decisions for the project.

Trust was something we built up with time. Good decisions, as well as some good old-fashioned values like grit, care, candor, and humility, helped build that trust.

With this experience behind us, we are now ready to take on the next big project—which is what our final blog in this series will discuss.