Multiple versions / Updating doc for older versions, and applying to newer ones
Hello,
we are evaluating Scroll Versions for our own use, on http://confluence.ez.no, where we document our products.
We need to offer doc for every version at the same time. We have figured out how to achieve this, but are a bit annoyed by the lack of navigation helpers between the different versions (like the scroll down on symfony.com/doc/current/book/controller.html).
A larger problem we haven't figured out the solution to yet: We are currently releasing version 5.1 of our product, but due to very major changes, we aren't done with the doc for 5.0 yet. We also regularily need to update older versions of the doc, and reflect this on newer versions if no changes have been made on those pages yet. Our problem is that as far as we can tell, you end up doing the same work multiple times. Let's say you edit the FAQ page of version 5.0, and it hasn't been changed in 5.1: publishing the page won't update 5.1, will it ?
Please help us, we'd really like to use Scroll Versions ;-)
-
Hello Bertrand,
first of all, I would suggest that you author manage your docs in one space - the master space.
To handle multiple versions of a documentation, the recommended way is to publish each version to a separate space. Then you can add links to other versions in the navigation sidebar as described here: http://www.k15t.com/display/VSN/Changing+the+Content+Sections - you can even create a little user macro that has a version dropdown like the example you've mentioned.
In the master space you can also keep working on older versions. Every time you make changes to a version (e.g. to 5.0) you can again publish it to the DOC50 space (using the publish to existing space feature of Scroll Versions 2.0).
For the issue wih the FAQ: This is by design, that we have a copy of the page for each version. So you will have to copy/paste additional content from 5.0 to 5.1, if 5.1 has been changed.
Hope this helps.
Cheers,
-Stefan -
Hi Stefan,
Thanks for the helpful information. Knowing how to modify the navigation sidebar is invaluable. Previously, I was thinking it would be better to publish versions to different spaces. But in practice, I think you're right that staying within one space is the way to go.
Would you be able to point me to an example of the "little user macro" that can be used as the version dropdown? I would also really like to implement something like that.
Thanks,
Ryan
-
Hi Ryan,
in Confluence, you can create User Macros as described here:
https://confluence.atlassian.com/display/DOC/Writing+User+MacrosYou can use that to create HTML for a drop down list, that allows your users to switch between versions.
Cheers,
-Stefan -
This is exactly the question that I was going to ask, but I still have some uncertainties. Currently we are just publishing to PDF so we don't need to understand other space publishing yet.
This question remains for me:
If I have active versions 1 and 2 that go to different audiences but are substantially the same, can I make changes to version 1 that will transfer automatically to version 2?
Thanks
David
-
Hi David,
unfortunately, changes in version 1 are not taken over automatically to version 2, as Scroll Versions doesn't keep track of the content structure of a page.
However, another great feature of Scroll Versions besides the option to work on multiple versions within the same space is the variant management functionality.
Variant functionality enables users to document similar products within the same space – avoiding duplicated content, and minimizing the effort needed to maintain this content. However, you can also use it to manage documentation for multiple target groups (for example an Admin Guide and a User Guide) within the same space.
You can make whole pages available for a variant by assigning specific attributes – or use our conditional content macro to make individual paragraphs available. Later, when you’ve finished creating content, you have the option to publish or export specific variants only: in other words, you only publish a specific set of pages.
Cheers,
Peter -
Hi David,
we highly recommend to use the includeplus macro to include versioned pages (see https://www.k15t.com/display/VSN/Enhanced+Content+Reuse for further details), as this macro can properly resolve the specific version context.
However, as it's currently not possible to include pages from other spaces (this requirements is tracked here: https://k15t.jira.com/browse/VSN-766), you might - as a workaround and if your pages are not versioned (meaning they are stored in a space without Scroll Versions activated) - also use the ordinary include macro (please note that this is only a workaround until VSN-766 is implemented and is not officially supported).
From your previous comment I assume that should work for you, however, if you'll give us some further details about your specific use case, we'll be able to check that.
Best,Nils
Please sign in to leave a comment.
Comments
10 comments