What is a recommended way to use Confluence to manage the documentation of a software system

[Craig Senior]

What is a recommended way to use Confluence to manage the documentation of a software system with many COTS and custom components, released individually and collectively. How best to store and assemble it?

Assumptions:

• Documentation includes install, upgrade, administration, and user.
• Documentation is written as Confluence pages.
• Code is developed and managed separate from documentation.

[Matt Reiner _K15t_ · Accepted solution]

Hey @Craig Senior

May team has also put together a collection of best practices for creating documentation in Confluence. It's called Rock the Docs. I hope you find this helpful.

For documenting different components, some document all of them in one space, some in individual ones. Sort of similar to how we've broken up the documentation for each of our apps into individual spaces.

If you version each of your components separately, you'll want a versioning strategy for sure. You might consider my team's app Scroll Versions for this. You can also create variants of your content, so you could have just one documentation space that has some unique content displayed to admins or users.

Also, you could also Consider Scroll Viewport, which is the app we and Atlassian use to create our online help centers. It's all Confluence in the background, but your readers get a legit help center experience which your team can customize to fit your brand.

Also, I highly recommend the #confluence channel in the Write the Docs Slack. That part of the community is full of folks creating documentation using Confluence.

[Craig Senior]

Now we're getting somewhere... Reading, I can see you understand the problem.

[Mike Rink · Accepted solution]

Hi @Craig Senior , our apps' documentation is written and shared in Confluence - https://wiki.comalatech.com. We use our own app, Comala Publishing, to manage a publishing process that separates draft content from final content. Everything is published to space that has anonymous access, and thus is viewable by our audience. We also use an additional app, Refined Theme, to improve the UI and UX of the documentation. 

We put together a short video that talks about a similar use case (in this case, sharing HR documents, but the principles are the same): https://www.youtube.com/watch?v=-2DyjZDNja0. 

Best of luck, happy to provide more info if it helps.