uPortal developers,
I gave this lightning talk at the conference:
* Slides: https://speakerdeck.com/apetro/github-as-wiki
* Video: https://www.youtube.com/watch?v=0CIVNiwxGpE
* Transcript: https://gist.github.com/apetro/5551a75bc6df9a0b943a
Short version: Let's consider moving uPortal manual documentation (that
is, documentation that documents specific versions of
uPortal-as-product) into text files in Git source control right there
with the product it documents, to be versioned with and updated in the
same pull requests with the changing code.
My next action on this is to proof-of-concept doing a little uPortal
documentation in this way. I'm currently excited about trying to use
ReStructured Text and ReadTheDocs for this -- that would arrive at a
strategy where product documentation is in human-readable
human-writeable text files in source control, and yet builds and deploys
-- plugging into the existing Travis-CI continuous integration process
-- to ReadTheDocs for lovely presentation, complete with UI for
switching which branch/tag of the documentation you're looking at.
Seems to appropriately balance documentation-is-source-code with
documentation-is-polished-deployer-facing-product. Or at least seems to
have great promise.
So. At some point I (or someone else!) will have that proof of concept
on a demonstration branch, and then let's see how well that works...
Kind regards,
Andrew
--
You are currently subscribed to [email protected] as:
[email protected]
To unsubscribe, change settings or access archives, see
http://www.ja-sig.org/wiki/display/JSG/uportal-dev
