nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

Best structure for documentation for multiple products?

Kyivkpic Kyivkpic

My project is to completely transform technical documentation for an software company with multiple (more than 15) products. We have decided to go with confluence instead of Framemaker.

My question is what is the best way to organize multiple documents (quick start guide, admin guide, etc.) for a large number of projects. I was thinking that it will be best to create a new space for each product. Is there a way to include all docs for all products in one space with how the page trees work? It seems like it would be less confusing and easier to keep docs for each product in a separate space. Am I wrong?

Comments

unknown

Hi @Kyivkpic Kyivkpic,

Great post! Confluence is a great choice for technical documentation!

My question is what is the best way to organize multiple documents (quick start guide, admin guide, etc.) for a large number of projects. I was thinking that it will be best to create a new space for each product.

I also think that you should go with one space per product. The biggest reason for this IMO is that pages have to have unique names in a space. So you couldn't have two "Getting Started Guide" pages in the same space for different products for example.

Also, using different spaces comes with other benefits as well, such as being able to filter by space (product) in the Confluence search.

Is there a way to include all docs for all products in one space with how the page trees work?

Well, you can not do this in the sense that you could include the full page trees of the other spaces into the navigation in the sidebar. You could however create a "Portal Space" which has only one page and links to the product spaces. On that page, you could use macros like the Children Display Macro to display the page trees of your product spaces in the page content to make navigation easier.

If your goal is to make your documentation publicly accessible, I'd also recommend taking a look at an app by my team: Scroll Viewport for Confluence. With it you can publish your documentation as a real website, running on a custom domain. It will also generate a portal page for you and comes with many other great features that are useful for a public help center such as a Google Analytics integration, SAML authentication, and theming and styling options.

In fact, for getting ideas on how to structure your content, you could even check out some of the live sites that have been created with it and see how others do it. The page trees / navigation you see on these Viewport sites resemble the page trees in Confluence (and every product / app is its own space or Scroll Document):

K15t Help Center (our own): https://help-cloud.k15t.com/
Adaptavist Help Center: https://docs.adaptavist.com/
Easy Agile Help Center: https://help.easyagile.com/

If you have any questions about Scroll Viewport, let me know.

Cheers,
Sven

Bill Bailey

I am a huge fan of FrameMaker, used it for years, and it is the gold standard for documentation. But moved to Confluence for documentation 10 years ago due to the collaboration abilties.

How I have organized my Confluence instances (have built doc systems for three different customers to date), is by doc type. So for example I have all user guides under a space called User Guides. Then a set of child pages to segregate by product. I also use labels on each of the individual doc pages that reflects the doc number (eg, ug001) to make reporting easier.

Yes you will have the issue of page name collision, but we use Scroll PDF exporter, and use thier macro to rewrite the page title on export -- allows us to have a longer unique name, and a shorter name that appears in the PDF.

Lastly, you will probably want to be on server and not cloud, for two reasons:

Greater ability to customize your solution with CSS, and user macros
Configuration control. You control when and if you upgrade, or add/remove macros.

unknown

Hey @Bill Bailey,

All great points, and great idea to use the Scroll PDF Exporter like that! But regarding Server, don't forget that it has an EOL:

Support for Atlassian Server products ends on February 2, 2024

In fact, if @Kyivkpic Kyivkpic isn't using Server already, they won't be able to start doing so anymore:

As of February 2, 2021 PT, we will no longer sell new licenses for our Server products and will cease new feature development in our Server product line.

Cheers,
Sven

Bill Bailey

Yes, I am painfully aware. ;-) So he will have to pay $$ to go to Data Center (wasn't sure if he already had access to server). It will be cheap versus dealing with all the limitations and frustrations with the Cloud version. And if he needed to buy a FrameMaker license for each author, also not cheap.

And I bought a few extra server licenses to put on the shelf just in case. ;-)

IMHO, a very bad decsion on the part of Atlassian to try to push customers to the Cloud version before it is completely usable by power users -- so many missing features.