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

[Matthew Joslin_AppFox_]

For a maintainable technical knowledge base in Confluence, the structure that scales best is: one space per product (or major audience), a shallow page tree organised by task/topic rather than by team, and labels for cross-cutting themes (e.g. 'faq') so the same page can surface in multiple filtered views without being duplicated.

For version-specific docs, keep one canonical page per topic, and branch by child pages or labels per version rather than cloning whole trees. That keeps search clean and avoids stale duplicates.

Where it usually gets harder is keeping docs reviewed and current as versions move on. Workflows for Confluence adds review/approval states and expiry dates to pages, so each doc has a clear draft → review → published → re-review lifecycle. Worth checking against how version-specific your content really needs to be, but could be handy.
The workflow builder is built to be easy to use by any team, and includes automated actions like applying those labels I was talking about above!