Note: this is a reasonably faithful verbatim transcript of a live conference lightning talk, not a re-worked blog format presentation of this content.
Links:
GitHub as Wiki, or, Version your Product Documentation in the same Git Repo with your Product.
I'm here to talk about versioning documentation with the product.
So, what's a "wiki" anyway?
As wiki is, I suppose, a think where it's like easy to edit and easy to edit directly through the Web without special tools.
We've got a manual for the uPortal product. Well actually we have a Confluence space for each of several versions of the product. And that's cool. The killer feature of that solution is the fact that Laura McCord did it and the number one feature in doing anything in open source is that someone do it, so that's fantastic and I wouldn't say a single thing against it.
But... it turns out Laura has gotten a new job not doing that. Which is really sad. She was doing a great job.
So. Maybe there's some issues with using a Confluence space for a version of the product as the manual.
Confluence is WYSIWYG only so cherry picking and merging changes when a documentation improvement affects multiple "branches" is painful and manual. I can simplify that and say Confluence is WYSIWYG only so ... painful and manual.
There's technical debt in divergence between the software and the product, between code and its documentation. That is not a moral statement, that is a technology and process statement, in that it's not possible update the documentation in the same transaction that you update the code because they're in completely separate tools. So you're left doing silly things like, well, I'll update the documentation before the feature lands in the expectation that it might land or I'll put a lot of caveats in the documentation and say "well at some point this will work like this but it doesn't work like that now".
Well, what does GitHub bring us? Text files in GitHub, I would argue, are wiki because right in GitHub I can edit them, and I can edit them in my browser if I don't want to pull down the text files and edit them locally and I can edit them even if I don't have push privileges in the repo. So, one argument for a wiki separate from your source control is that the point of a wiki is for it to be easy and to invite more people to help because you need more people to help with documentation. Minimize the barrier to work on documentation, because we certainly need more work being done. So that'd be great. Well, you can edit, you can edit right in your browser. You can edit even if you don't have write access to the repo. If you do it, then GitHub will automagically fork the repo for you and set you up to edit it and go ahead and do a pull request for your change just like a code change. And so you can version the product documentation with the product.
This is AngularJS. They've got a docs directory right in their repo. This has some significant advantages in that at the time you're making the change to the product, you also make the change to the documentation about the product. It comes in as a single transaction. Features branches are a good thing. Pull requests are a good thing.
And this is a way to move some of the responsibility for maintaining documentation perhaps off of one person doing documentation coordination and onto perhaps many people who are making changes to the product. If the documentation is managed in a way like this then you if you are proposing a change to the product, maybe you should go ahead and propose a change to the documentation to document the change you're proposing on the product. And that can all get reviewed and spiffied up in a feature branch and come in all of a piece. The act of merging the feature is also the act of updating the documentation.
So my goal in this talk was to lay out that idea, so that uPortal folks and others can think about how that might fit. But mostly where I'm at is that the documentation of the product should be versioned with the product so we get this natural workflow.
Wikis are good for documentation that's not about a particular version of the product. So by all means, commented use cases from the community, and sketching versions of future versions, out of band contributions, are wonderful. Wikis are good. You should collaborate and share. But maybe wikis are not the right tool for products. Thank you.