Upgrade to Pro — share decks privately, control downloads, hide ads and more …

GitHub as Wiki

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/ .

Andrew Petro

June 03, 2014
Tweet

More Decks by Andrew Petro

Other Decks in Programming

Transcript

  1. GitHub is your wiki Versioning documentation with the product it

    documents. Andrew Petro / My UW-Madison 2014-06-03
  2. 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…
  3. 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
  4. Coherent commits, feature branches, pull requests • Develop the documentation

    with the feature. • Merge the documentation with the feature.
  5. When to use what • Text files in GitHub •

    Document the (versioned) product ! • Wiki • Documentation that’s not about (a version of) the product
  6. 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.