Using Confluence 'spaces' for documentation
acheetham at ocad.ca
Wed Sep 1 20:37:38 UTC 2010
I mentioned today in stand-up that I want to find a better way to version our documentation. I'm still investigating options (and will continue to do so), but one possible scenario is to use Confluence spaces. I'm still learning just what you can and can't do with spaces, but so far it seems promising. I thought I'd float the idea now, in case anyone has opinions one way or the other.
Here's what I'm thinking so far:
Each version of Infusion would have its own Confluence space for any documentation that is version specific. The space would be for documentation, and documentation alone. This would allow us to customize the look, stylesheets, layout, etc. to be a bit more suitable for documentation without messing up the main wiki. It would also allow us to use the navigational sidebar to greater effect.
Spaces can be copied, so we could conceivably keep a single space for "current" documentation, i.e. a staging area which we try to keep up-to-date with trunk, and so which would be considered wild and not necessarily complete. When we're ready to cut a release, we would finalize the docs and then copy the space into a numbered space that would then become "the" documentation for that release (similar to cutting a tag in SVN). The spaces are still editable, so we can update the docs for a given release to reflect any maintenance updates.
Pros of this approach:
- all of our docs are already in Confluence, so migrating would not be as great a chore as migrating to a completely different system
- the wiki is easily editable by all developers (so everyone can help keep the documentation up-to-date)
Cons of this approach:
- Confluence might not be as flexible as other options in terms of layout, styling, embedding dynamic examples, etc.
Does anyone have any other thoughts on this idea?
Anastasia Cheetham Inclusive Design Research Centre
acheetham at ocad.ca Inclusive Design Institute
More information about the fluid-work