We know how important good documentation is for the platformOS community. This is why we started building our documentation site based on a strategy that ensures that our documentation will be your most trusted asset when working with platformOS.
This article series describes our process, with in-depth insights into our approach, decisions, and plans. We have planned four parts for this series, each describing a unique aspect of our journey:
All these articles together will show you a complete framework for building a documentation site on platformOS.
We are continuously working on our documentation, but decided to make it public early on to get valuable feedback and show you the whole process, so please expect the documentation site to change and evolve while you learn more about it through these articles. At the time of the publication of this article, our documentation site is in alpha.
Because of the strategic role our documentation plays in the adoption and use of our product, we approached the development of our docs with a mindset that ensures that:
All throughout the process, we used the user-centered, solution-based Design Thinking method.
At the start, we explored our audience, our documentation needs, existing and missing content through in-depth interviews and workshops. In Design Thinking terms, this was the Empathize phase. Then, we defined personas and our Content Inventory (Define), and shared our ideas for content and features through a Card Sorting exercise (Ideate). Based on our findings, we created a sitemap and prioritized content needs. Layouts, wireframes, and content production (Prototype) started based on the results of our discovery phase.
We decided to follow an iterative, docs like code approach: at each stage, we work with quick feedback rounds, deploy often (multiple times a week), and improve features and content based on feedback from real users (Test). We have an overarching plan outlined for our documentation that we keep in mind, but we always focus on the next couple of action steps we’d like to take.
We knew that knowing our audience is the key to writing documentation that best supports their needs. For efficiency, we also needed to know what we already have, and how existing content could be reused. This is why we started our journey with a discovery phase. By asking the right questions, we got the answers we could build on, and outlined the Information Architecture and content needs of our documentation site.
The first output from our workshops was a detailed description of each persona — the types of users that will be interacting with our documentation site. The user personas help team members share a specific, consistent understanding of various audience groups. We use these personas to see how well proposed solutions meet their needs, and to prioritize features based on how well they address the needs of one or more personas. We plan to revisit and revalidate these personas in later phases of the project as the product is evolving.
We found out that we have the following four main personas:
Descriptions of our proto-personas with sample photos and names to make them easier to relate and refer to
Taking into account our proto-personas’ needs and sites we considered our inspiration, we created a detailed list of content from our previous documentation site, and identified missing, reusable, and non-reusable content for our future site.
Content Inventory ready for the Card Sorting Session
Through a Card Sorting exercise, we defined connected elements, and mapped out the best site structure for our goals and proto-personas.
Screens from Mural during our Card Sorting sessions
Based on the Content Inventory and the results of the Card Sorting sessions, we outlined a sitemap for our future site. Our sitemap shows the structure of the site. We can also use it as a roadmap to keep track of site improvements, content needs, and project phases, because following our iterative approach, we created several sitemaps — one for each phase of the process (e.g. alpha, beta, etc.).
Sample page from our sitemap
We have already changed some parts of our sitemap based on new information we gathered and business decisions we made. For example, we are now planning to build a separate community site, instead of having a community section on our documentation site. We decided to link to content on platform-os.com (like the blog, terms & conditions, etc.) in the beginning to focus on other parts of the site, and reevaluate these sections later. We believe that both product and content development can benefit from a process that allows for such flexibility.
Now that we had data about the personas and our sitemap, we put the data into the proper context and outlined coherent stories. These stories, similar to user journeys, show the order of actions taken by the user personas during their interaction with the site. During the Card Sorting sessions, we explored areas of interest for each user persona. This helped us see where to focus first to help them from the beginning. We also validated the importance of these areas to assign higher priorities to the ones that need more attention. We then displayed their interaction with the site on the sitemap.
Exploring areas of interest based on the persona’s actions taken on the site
Persona interactions with the site displayed on the sitemap
This concluded our Information Architecture phase. We have discovered and organized all the information we needed to continue on to the next phase, where we started creating templates for content types, building the wireframes for each page, producing content, and making decisions about design.
We will discuss these aspects in part 2 of our series. Stay tuned!
We involved UX Strategist Katalin Nagygyörgy in our process from the start. Through our collaboration, we could extract and collect all the necessary information using tried and true research methodologies and UX best practices.
Ensure your project’s success with the power of platformOS.
