Using a Wiki for Collaborative Documentation TOSW - Presenter Notes

From The_Open_Source_Way

These are the notes being used for a presentation on Using a Wiki for Collaborative Documentation TOSW.

checklist

1. dial in to phone num. at 11:45
2. Have demos, documents ready to go on machine I'm presenting on
   • gwibber and noisy stuff off
   • windows minimized save browser and emacs
   • Stand-alone browser ready with:

• 1. • tosw.org front page
     • sandbox page

timeline / outline

•  :00 - :03 -- Introductions
•  :03 - :05 -- Focus of talk, goals
•  :05 - :10 -- Wiki collaboration methodology
  • generic & specific
  •  :10 - :25 -- Demonstration of methodology
  •  :25 - :35 -- Wrap-up

Focus of talk, goals

This talk presents a collaboration methodology that uses a wiki and a common set of practices grounded in the open source way. The goal of the collaboration is community documentation, which is content created by a community for its own purposes/needs.

For example, I was at OSBridge last week, and each session page has a wiki link. Audiences members are encouraged to use it for taking session notes, and multiple people can edit parts of the notes simultaneously. At certain conferences I've seen a very high degree of session note taking, so the conference is literally documenting itself as it proceeds. I can refer back to a discussion or decision that was reached in one of those sessions, using the realtime log/minutes created by the audience.

Wiki collaboration methodology

We are building on what Wikipedia teaches us. So, we point to their how-to and why information.

• MediaWiki help pages provide syntax information and best practices on page authoring:
  • https://www.theopensourceway.org/wiki/Help:Editing points to http://fedoraproject.org/wiki/Help:Editing
  • http://fedoraproject.org/wiki/Help:Wiki_rules_and_etiquette
  • http://www.mediawiki.org/wiki/Help:Contents
• Fedora Project grew up special rules
  • to handle our unique situation
  • to make it easier to convert wiki pages to DocBook XML so it can be processed by the same tools that build RHEL docs.
• Building a book with 3 chapters
  1. Create a new page to be the top-level of the book by typing in the URL or making a stub link. The name should be descriptive, natural language, not CamelCase, and not redundant (e.g. adding Fedora to the name of a guide on fedoraproject.org.)
     • Using a Wiki for Collaborative Documentation TOSW
  2. Edit the new page. Introduce the book, scope, etc., then create a table of contents that are stub-links to the chapters.
     • Using a Wiki for Collaborative Documentation TOSW - Introduction
     • Using a Wiki for Collaborative Documentation TOSW - Standing on The Shoulders of Giants
     • Using a Wiki for Collaborative Documentation TOSW - The Process
  3. Add it to at least one category immediately. It may have its own self-named category, too.
  4. Create the second-level nested sections
     • Each page is itself the first-level nesting
     • Use Review to check for syntax mistakes
  5. Save at this state because:
     • Save often is safer, less work lost
     • Once saved, you are more likely to share the URL
     • Once saved, it shows up in the wiki recent changes list
       • Release early, release often
     • The work you save is the work others have to build on
       • You may have reason to go suddenly, leave it so others can pick up where you left off.
  6. Each sub-section can now be edited independently.
  7. A common trick with wiki pages is to stub out all the sections.
     • Gives an outline to work against.
     • Makes it easy for others to work on part of the outline.