Best way to organize technical resource pages and documentation for users?

[David Romero]

Hi everyone,

I'm looking for advice on how to better organize technical resource pages so visitors can quickly find the information they need.

I manage a website that provides information and guides related to PS2 BIOS resources: https://ps2biosonline.com/

As the amount of content grows, I'm interested in learning how others structure documentation, FAQs, version information, and support pages to improve the user experience.

For those using Atlassian products or managing knowledge bases, what approaches have worked best for you?

• Separate guides by topic?

• Use a centralized knowledge base?

• Create version-specific documentation?

• Any recommended best practices?

I'd appreciate any suggestions or examples from your experience.

[Kris Klima _K15t_]

Hi @David Romero and welcome to the Community

I'm a tech writer and content architect... and now I'm working for a company (K15t) that makes Confluence apps for... tech writers and content architects.

I used Confluence (and apps that extend Confluence functionality) for author and publish documentation for a wide variet of products - mainframe software that's in continuous development from the late 1970s to online SaaS platforms.

Let me address your main points:

• Separate guides by topic?
  A page should cover one standalone topic, something that can stand on its own. But I advice people to think about READERS. How they would use the product/docs and what they would expect from the page. It needs to help users to accomplish a specific thing.

• Use a centralized knowledge base?
  If you have more products, you should have a centralized site with a landing page that allows users to navigate to the specific products. If those products together form a suite, you need to make sure you can handle mechanics of cross linking those products.

• Create version-specific documentation?
  That depends on your product. Is it one size fits all / continuous delivery? Or do you have fixed version and support multiple versions at the same time? We have both. Our Data Center documentation is versioned (semantic versioning), Cloud docs are one size fits all. See https://help.k15t.com/scroll-docs/latest/server and toggle Data Center / Cloud
  As @Tomislav Tobijas pointed out, for proper semantic versioning, you need an app.

• Any recommended best practices?
  See below :) 

I'm sharing a couple of resources from our Learning portal. I wrote them with intention to teach people how to think about documentation before they make decisions that will impact the entire documentation life cycle:

Documentation guide:

https://www.k15t.com/rock-the-docs/the-documentation-guide

Why use Confluence for documentation:

https://www.k15t.com/rock-the-docs/confluence-use-cases/why-documentation-in-confluence

How to choose your documentation tool:

https://www.k15t.com/rock-the-docs/the-documentation-guide/author-write-documentation-that-actually-gets-read/how-to-choose-your-documentation-tools

These articles reflect my 15 years of experience and the collective experience fo our company.

Hope this helps. Feel free to reach out if you want to learn more.

[Tomislav Tobijas]

Hi @David Romero ,

This is mainly a question for tech. writers, but I can maybe share my experience and what I've seen so far.

It all depends on org to org, but some things are standardized:

• There are separate spaces for team, project, and product documentations
• There are usually separate spaces for internal and external KBs
• I've mainly worked with product docs, so these are separated by products themselves, but there are also separations by what you call topics - e.g., Troubleshooting Manual, etc.
• Yes for centralized KB - don't have separate systems or tools for storing and sharing documentation. It usually has a negative outcome among users and customers 👈
• Version-specific documentation... well, this is a tricky one. From my experience, the best bet would be to use some Marketplace apps for version-switching. That's if you don't want to have multiple duplicated pages with similar content 😕

💡 Now, things also depend if you're using Cloud or DC. In cloud, use the power of Rovo. It can suggest a really good structure and also clean up outdated content (or just recommend what to update based on dates or usage/views). 

When we talk about official resources, here's one guide on some of the best practices when it comes to this app: Confluence best practices 

Hope this helps.

Cheers,
Tobi