GitHub as Wiki

Version product documentation with the product it documents. Recording at https://www.youtube.com/watch?v=0CIVNiwxGpE ; Transcript at https://gist.github.com/apetro/5551a75bc6df9a0b943a ; Originally presented at http://lanyrd.com/2014/apereo/sdbbhk/ .

Transcript

1. GitHub is your wiki Versioning documentation with the product it documents. Andrew Petro / My UW-Madison 2014-06-03
2. “wiki” • Easy to edit via Web without special tools
3. uPortal manual spaces in wiki
4. Features • Laura McCord (current uPortal documentation coordinator) is a wonderful and a generous volunteer. • It turns out this feature is more important than any of the issues, since with care and determination, the issues are just noise. • but…
6. Issues • Confluence is WYSIWYG-only, so “merging” and “cherry-picking” documentation fixes across “branches” is painful and manual • Confluence is WYSIWYG-only, so … painful and manual • Technical debt / divergence between code and documentation • This is necessarily so by the process
7. Text files in GitHub *are* wiki
8. Edit through GitHub
9. Edit even if you don’t have push
10. Version product documentation with the product
11. Coherent commits, feature branches, pull requests • Develop the documentation with the feature. • Merge the documentation with the feature.
12. When to use what • Text files in GitHub • Document the (versioned) product ! • Wiki • Documentation that’s not about (a version of) the product
13. Meta • Licensed to you as CC-BY 4.0 , or • Apache 2 ; at your option ! • Opinions expressed herein are those of the presenter and not necessarily those of the University or of Apereo.