If you (Atlassian) had the Scroll Versions plugin when initially structuring your documentation, would you have kept with the space per product version?

Question

If so, how would the use of the plugin change your structure?

If not, what are the use cases that keep you tied to that structure?

Our tech comm team is working through a proof of concept where all documentation will be authored in Confluence, and we are trying to figure out the best structure for minimizing the overhead in managing the content and numerous spaces.

Traci Wilbanks · Answer

It does help, Sarah!  Thank you for the thoughful answer.  Your point about the lack of fixed URL with the alternate practice is enough to steer me away from that option.  There are enough hurdles in finding information; introducing a new type of hurdle would run contrary to our mission.

SarahA · Answer

Hallo Traci

That's an interesting question. I don't think we'd have changed the structure of the documentation if we'd had Scroll Versions when we did the initial design. Having a space per product makes a lot of sense, because each space can then address a specific audience: the customers who have that product.

In fact, we take it even further and have a space for each major version of each product. So, there are many spaces for each product: one for each major version.

There's one change we've considered making, although it isn't related to Scroll Versions. It's about how we use the main space for each product. At the moment, the main space holds the latest version of the product, and we create archive spaces for the earlier versions. The change would be that the main space would hold just the overviews and release notes for the product, and the latest version of the product would have its own version-specific space too.

For example, let's say the product is called "ChocTactics" and the latest version is ChocTactics 4.3. Let's say that ChocTactics 4.4 is soon to be released.

Under our current versioning practice, we'd have a space with a key of CHOCTACTICS. It would hold all the docs for ChocTactics 4.3. We'd also have a space CHOCTACTICS042 holding the docs for ChocTactics 4.2, and CHOCTACTICS041 for version 4.1, CHOCTACTICS040 for version 4.0, and so on. When we release ChocTactics 4.4, we would create a new space called CHOCTACTICS043, copy the content of CHOCTACTICS to that new space, and then update the CHOCTACTICS space to hold the docs for version 4.4.

CHOCTACTICS (version 4.3)

|

__ CHOCTACTICS042 (version 4.2)

|

__ CHOCTACTICS041 (version 4.1)

|

__ CHOCTACTICS040 (version 4.0)

In the alternative versioning practice, the CHOCTACTICS space would hold only the overviews, release notes, and other information that is not specific to a given version of the product. We would have the CHOCTACTICSnnn spaces, just as above, but we would create the CHOCTACTICS043 space as soon as we started planning for and documenting version 4.3, and similarly the CHOCTACTICS044 space for version 4.4.

CHOCTACTICS (overview)

|

___________________________________________________________

|                                     |                                   |                                 |

CHOCTACTICS043         CHOCTACTICS042        CHOCTACTICS041      CHOCTACTICS040

In many ways, the second practice is easier to manage. But it would mean that there is no fixed URL to give customers, marketing people, and so on, for each page in the docs. Every link into the docs from anywhere would have to know which version it needed. Also, people would have to keep moving to a different space when they wanted to comment on the documentation, put watches on the spaces, or have RSS feeds on a space.

For the above reasons, we're sticking with approach 1 for the moment at least. The Scroll Versions plugin fits in very nicely, as it is designed to make this sort of workflow possible.

I hope this helps!

Cheers, Sarah