Content Inventory and Planning for Docs

According to Kontent AI, Content Taxonomy refers to a scheme of classification used to organise and categorise content. Simply put, it’s a list of terms that helps you manage all files and assets in a content repository. It usually comprises three parts: categorization, tags and metadata. Read more about how these parts work together to make it easy to find your content online.

In the previous section, we learnt how to use a journey map and mental models to draw up a simple information architecture. Now it is time to take inventory of the existing content, strategize on the Content, define the scope and goals based on results from the survey and research, and take inventory of the content based on the different target audiences. Start by doing a thorough content audit for an existing docs platform. Determine what content is up-to-date and no longer of use, what content should be added, what needs to be reviewed, and which teams are responsible for maintenance. Also, consider setting up CI/CD pipelines for documentation; this ensures an ecosystem approach to documentation maintenance is adopted. This can be done using a regular spreadsheet or any tool you like. Here is a simple template to help with this.

Things to take into consideration…

Before you begin the content inventory, you should be aware of the following:

• Determine the amount of traffic lost or gained due to moving or deprecating content. To do this, start by planning your URLs. Buy the Docs Inventory and Taxonomy Builder Template.

• Note that when content is moved, the URL automatically changes. This means a redirect setup is needed before the site goes live to avoid visitors to your documentation encountering many 404 pages.

• Consider conducting an internal audit of the content to find broken links, outdated images, and content and shorten the URL levels. This will prevent the user from navigating deep into the content before finding it. Write an automated script that can detect broken links. Run this as part of your CI/CD pipeline for bonus points and regularly using cron jobs.

• Pay attention to the site metadata and how the URLs are named for better SEO, findability, and effective search. Also, please pay close attention to how the URLs are unfurled in applications or social media where you expect them to be shared.

Populating the categories…

1. Concepts: The /concepts bucket or section should contain conceptual information about the platform and technology. This means the Glossary, FAQs, and concept definitions should be found in this section. For example, Ethereum is a programmable smart contracts platform that uses Proof of Stake. This means the concepts section needs to explain the foundations of the blockchain, why a programmable smart contracts platform is necessary, the technology stack and how Ethereum uses Proof of Stake to validate transactions.

2. Developers: The /developers section, depending on your organisation's needs, should rank higher. Generally rank the section where you expect action to be taken to achieve an overall goal. For example, suppose a developer integrates your API or SDK or can use a quick start guide to deploy a transaction. In that case, this contributes to increased network and transaction activity. This section ideally should contain general setup instructions, an integration guides section for API / SDKs, a blockchain primer for developers new to the platform, and other resources like connecting to the node, deploying smart contracts, etc.

3. Node Operators: As the name implies, node operators are simply node operators. This bucket or section should cater to them and contain information on node setup, configuration, running, and maintenance.

If developers are a secondary audience, this should be highly ranked after them. However, depending on your organisation's needs and wants and information from the user research and survey conducted, if node operators are the primary users of your product, then this should rank first.

4. Users: Depending on the user segmentation, users can refer to general users of your tools or product. These tools and products mostly have a user interface. In the case of an API or SDK integration, consider branching out into another bucket called “Developers” since they’re most likely to integrate the APIs and SDKs. See the example above in the developer section. The user’s bucket should typically contain information and external links to products or guide content.

Note that this is a simplified example of IA structure. Other content types do not fit into these three categories. Some platforms refer to that content as Resources or Knowledge bases (Tutorials, guides, etc.).

An Improved Information Architecture

In the previous section, we drew up a simple information architecture and explored the types of content needed for each section. After taking stock and inventory, let's develop our IA to reflect the developer journey.

The diagram above categorises content into four main areas: Concepts, Developers, Node Operators, and Users. These categories form the foundation for your information architecture (IA). Depending on how you structure your content, you'll find subfolders or files within these base folders.

Here's an example of how this structure can be applied to finding setup instructions for developers: A developer looking for setup instructions would likely find them in the /developers/setup.md file. If the setup instructions differ for different operating systems (OS), such as Windows, Linux, and macOS, you can create separate sections within the same Setup.md file. However, if the setup instructions become too lengthy and complicated to read on a single page, consider using a readability test, such as the Flesch-Kincaid Reading Ease test, to assess readability. If your score suggests the content is difficult to understand, you can create subfolders within the /developers/setup folder to organise instructions specific to Windows, macOS, or Linux users. See the recommended levels for a URL structure.

Next, we will explore the docs toolsets, considerations and platform selection depending on your use case.

Resources

• Interaction Design Foundation

• NNGroup: Mental Models

• Diataxis Framework

• Docs Inventory and Taxonomy Builder Template

Huge thanks to Brendan Graetz for the review and feedback.