How We Updated the Planet 4 Handbook, as a Community

The online world constantly evolves and documentation obviously has to follow. The Planet 4 Handbook is a vital resource for our P4 Community and regrettably, maintaining this resource has been difficult. This meant that the Handbook was out of date and in need of a big update. A challenge, to bring a dynamic, comprehensive, and up-to-date Planet 4 Handbook!

Ownership for the Handbook

The traditional approach to documentation updates typically involves a few designated individuals, but we aim to include the community in the ownership of the P4 Handbook. After all, it’s the community that has to use the P4 tools, so having the community participate in the process of the documentation seems logical. This collaborative approach transforms static information into a living entity, involving everyone in sharing their knowledge and expertise. Creating documentation that is comprehensive, accurate, and relevant to meet the community’s needs.

This has been a challenge on several levels:

• Resource Constraints — Call it limited resources, lack of ownership, … There wasn’t really someone regularly keeping an eye out on the content of the Handbook.
• Changing Technology — We adore the work that the P4 Devs are doing on a daily basis, and regularly releasing fixes and new features. However, as the technology evolves, the documentation has to be updated too to reflect these new features and changes.
• Complexity — There’s just a lot in the Handbook. And as we kept adding things, the documentation became complex, making updates challenging.

Step by Step

Content inventory

We first started by creating an inventory of everything currently on the Handbook. This audit gave us a solid overview of what was available, what was missing and what needed updating. It also gave us a first view on where navigation through the Handbook could be improved.

Content inventory learnings

While an incomplete content overview may not provide a proper comprehensive view on the Handbook, it’s still a valuable starting point to improving everything. A guide, to make informed decisions and prioritizing what we’ll do next.

The main learning points were:

• Outdated information — Some pages were pretty outdated. Leaving gaps in the information as certain tools looked different or had new usability.
• Missing information — As new tools got added to Planet 4, they were not always properly documented into the Handbook.
• Structure — The structure of the Handbook was a bit too complicated to use. Not everything was easily reachable.

The Main Sections

After all the current content was noted, it was time to create a first version of the new Sitemap. This was an important step to reorganize the content available in the Handbook to an improved flow, so all relevant information was easily accessible. For the main topics, we landed on:

• Contribute — Different ways community can participate
• Create — Everything related to creating in Planet 4
• Explore — Exploring the Handbook and beyond, if you’re unsure what you’re looking for
• Manage — Everything related to managing the backend of Planet
• Updates — A place where updates and case studies get shared

Interlinking all of these pages had to be kept in mind as well, when building these five main categories. But more on that later.

Pages Redesign

The overview pages themselves needed a proper redesign as well. For this we asked ourselves the question: How would a visitor navigate through this page? (A good principle we had for the entire Handbook, to be fair). That’s when we came up with this structure, taken from the Posts page, under the “Create” section:

Relevant information that is normally outside of this specific section stays easily and quickly accessible this way. We included this principle in all pages where this was necessary, to improve navigation throughout the Handbook.

New Sitemap

Once we had our content audit, our new main sections, and knowing how we wanted to organize pages, it was time to create an updated Sitemap. All the pages that would and should have to be available in the Handbook, listed in one spreadsheet. (Well, first on post-its, to get a proper idea of everything, and then in a Spreadsheet.)

Why Spreadsheet? This way we could all keep an overview of the progress. We could easily spot gaps, see what was ready, and see what needed to be updated or created. This was also a good way to spot where we would need to redirect pages to, in case a certain piece of documentation got removed.

On to the Documentation itself

Now it was time to write. Check every single page to see if the information on it was still correct, add new screenshots, expand on information, make it more visual by adding videos and infographics, add the “also relevant” sections to other places in the Handbook to make relevant information more accessible, and so on. This took the most time, and is also something that is still ongoing, as Planet 4 is an ever evolving entity.

Luckily, the P4 Community jumped in from time to time by letting us know where the information was outdated, unclear, or missing bits of information. This helped us a lot to prioritize certain topics, such as the new Information Architecture.

Community Feedback

As soon as we believed we had a first proper version of the updated Handbook ready, we decided to present it to the P4 Community. A survey was created, asking the users:

• Is the information easily accessible?
• Is the information easy to understand?
• Is it easy to navigate through the documentation?
• Open notes (a space for any and all thoughts/ideas/feedback)

The survey included several questions related to these main questions. People were able to give a score from 1–5 and clarify their score. We also asked if they were open to chat one-on-one about their feedback, so we can properly understand their thoughts and implement changes accordingly.

With this peer review by the P4 community, the restructuring and updating of the Handbook could get into its next pages which was making the available information more accurate and reliable as well as fixing a few redirections we’ve missed, typos and more.

Continuous Improvement and Expansion

Now, refreshing the documentation has become an ongoing process in which the Community actively participates. This collective effort ensures that the Handbook remains a relevant and ever-evolving space. There’s a space to add ideas, report bugs, and a general contact form to get in touch with the P4 Team directly. On many pages, there’s also the link to the P4-General Slack channel, so the community can post a question there to help each other out.

In conclusion: Embracing community participation is key to keeping documentation relevant, accurate, and valuable in an ever-changing world.