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.
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.
| | | |
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!
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.
More and more people are building their careers with Atlassian, and we want you to be at the front of this wave! Important Dates Start the Certification Prep Course by 2 April 2019 Take your e...
Connect with like-minded Atlassian users at free events near you!Find a group
Connect with like-minded Atlassian users at free events near you!
Unfortunately there are no AUG chapters near you at the moment.Start an AUG
You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs