Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in
It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

Best structure for documentation for multiple products?

Hi :)

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?

2 comments

Sven Schatter _K15t_ Marketplace Partner Dec 07, 2021

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):

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

Cheers,
Sven

Like # people like this
Bill Bailey Community Leader Dec 07, 2021

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.
Like # people like this
Sven Schatter _K15t_ Marketplace Partner Dec 07, 2021

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 Community Leader Dec 07, 2021

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.

Like Kyivkpic Kyivkpic likes this

Comment

Log in or Sign up to comment
TAGS
Community showcase
Published in Confluence Cloud

🏠 Say hello to the new Confluence Home!

Hi Atlassian Community, My name is DJ Chung, and I’m a Product Manager on the Confluence Cloud team. Today, I’m excited to share a new and improved version of Home. The new Home helps you ...

37,699 views 27 124
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you