Details
-
Story
-
Resolution: Done
-
Medium
-
None
-
None
Description
Since switching to Confluence for the Infinispan docs (which we're pretty happy with) we've been thinking about the ways to handle multiple versions of the docs, for each release of the project.
I've evaluated the docbook export which you recommend, alongside other options such as export to PDF/HTML, copying the space or copying a subtree of pages. Conclusions from the team are:
Use markup inline (feature available since XXX)
------------------------
- Fixes are very hard
- Will get messy quickly
- Error prone
- hard for use to read
+ No infrastructure needed
Conclusion: Not suitable, it's just too messy
Export to static format (PDF/HTML)
----------------------------------------------
+ Confluence / Scroll Wiki make this easy to achieve
- docs cannot then be fixed post release
Conclusion: Not suitable, lack of post release edit is a killer
Export to docbook
------------------------
+ Good idea in principle, as it allows us to use existing infra such as git to store docs from then on
- Requires two different approaches to edit docs depending on what version they work on, which is confusing for people
- current process is very manual (export manually, transform manually, add release info manually)
- requires "double qa" - we check all the docs on confluence to make sure they look nice and then have to do so again for the exported version
Conclusion: Not suitable, it's good idea, but current process is too manual, will re-evaluate when this is improved
Copy subtree of pages
------------------------------
+ Fit's structure well as it keeps everything within a space
+ Allows post release editing within confluence
- Plugin for this looks unsupported
- Would need to be configurable to rename pages and update all links including includes etc.
Conclusion: Not suitable, plugin isn't mature enough, otherwise a good approach
Copy space
---------------
+ Structure is fine
+ Allows post release editing within confluence
+ Plugin looks stable, no naming issues
+ This is the approach taken by others who use confluence for docs (including atlassian)
Conclusion: This looks like the best option open right now.
Can you let me know what you think?
Pete