Documentation/Confluence revamp

Owned by Former user (Deleted)
Last updated: Jun 02, 2013
2 min read
  • Community-wide information that should be kept current in one place:
    • Security protocol and contacts
    • Most recent releases, announcements
    • Audiences, mailing lists, working groups
    • Community servers (QA, etc.)
  • Information that should have a reasonably parallel structure and location for each release:
    • Release notes
    • Install guide
    • Modules, dependency/utility versions, stealthed tools 

 

  • What else should we include? Please add here!
    • How to contribute?
    • Internationalization?
    • Accessibility
    • Sakaiger?

  • Strawperson plan:
1. Leave everything in place and mark it with a "community/development space" header.

2. Make a *simple* document inventory that lists what we think always needs to remain current and what should be locked to a release as "official" documentation, finding the existing pages that have this essential and relevant information.

3. Set up a new Confluence space (maybe another domain) and move/copy pages in #2 according to the doc set.

4. Link Jira to the new Confluence space. 

5. Create a small group with a practical schedule of dates for reviewing inventory and keeping it as a public punch list (and ideally working to make updates or do the housekeeping, but at the least identifying the needs on a defined rhythm and in a known spot and announcing them).
  1. Do we want to have documentation restricted to a vetted group of people?
    1. Reach out to Apereo?
    2. How do we attract people to participate? Keep barriers low?
  2. Look at other open source projects - they keep their documentation in a source control repository 
    1. Do we want to move away from WIKIs? Consensus is Yes (though keep confluence for legacy, but clearly mark it as not reliable)
    2. Keep Wikis... because we're used to it? because it has JIRA linkage?
    3. Use GitHub?
    4. Look at Moodle? DSpace? manages everything in a central repository and releases documentation.
  3. Own our sakaiproject.org repository for our tech documentation?
  4. Too much crappy documentation currently
  5. We need a decent process and a decent process - use source control, branch and tag entire body of documentation with each release.
    1. What is the base format?
    2. What do other people use for a publishing process?
  6. Get Funding?