Archive:DocsProject/DocumentationGuide/ExampleTutorial

Documentation Guide Example Tutorial

This page describes plans for the "Learn While You Do" Documentation Guide tutorial.

How It Will Work

Learning through doing is the best education for busy adults.

Someone needs to figure out how we would make an automatically erasable CVS sandbox. Everyone can't share the same one, because that would create needless complexity for the user. Maybe we can ship a set of scripts that sets up a disposable CVS on the user's system, preferably under $HOME. Otherwise we either have to:

• accommodate a user's sandbox on the main Fedora CVS, until such time as they throw their work away manually, or
• throw the sandbox away on a regular basis, meaning that we will be causing pain for whoever is learning on the system at the time the sandbox is emptied.

Neither option is as good as shipping scripts to mimic a remote CVS repository on the user's system. ElliotLee agrees as of 25 April 2005 IRC #fedora-docs conversation.

Here's my idea for the process, in a nutshell:

1. The Tutorial is organized in units, each one self-contained, yet building on the knowledge in previous units. 1. The supporting scripts build a $HOME/.fdp-dgtutorial directory. Might be something like this: (with more error checking 'n' stuff) a. The CVS repository is built into branches. Why is that better than separate directories for each tutorial chapter?

• Not sure... how about, because it means that the student doesn't need to check out the right module for each chapter? Always checking out the same module...
• The student can compare easily (with tags, right?) the end state of files after finishing a chapter with the beginning state of files in the next chapter?
• PWF: I'm lost now, even though I thought I understood this before... can anyone who knows more about CVS tell me whether this is sane?

a. Each branch represents an initial state for a unit of the tutorial. a. The first step of each unit of the tutorial is to check out the branch matching that unit, resulting in a known initial state. a. In the event of a horrible mistake, the user may revert to the unit's initial state rather than the entire tutorial's initial state. a. Each branch may be patched independently, so errors in one unit need not affect others. a. A user may run only those Tutorial units necessary. a. In the case that branch is not the right term, substitute a better CVS term above to provide this functionality. 1. The Tutorial includes a section on how to remove the supporting files, including scripts and the aforementioned directories.

TommyReynolds will help with the sandbox script stuff. We may simply go with separate directories until/unless we hit a wall.

Outline

This outline is split out so that it doesn't overwhelm the overall DocumentationGuide outline. The tutorial is not designed to be comprehensive on any specific subject. It gives a new user enough guidance to learn the ropes without overwhelming them with details. Specific detailed questions should be directed to mentors or the fedora-docs-list instead. All fedora-docs-list regulars should be prepared to answer newbie questions helpfully and in detail. The fedora-docs-list should be a model of courtesy and peer support for other mailing lists.

I. Introduction A. Why this way? (list suggestions, addressing complaints...) A. Goals/objectives A. Separate into units to make it munchable by newbies I. Global Preparation A. Check package installation (cvs, "Authoring/Publishing" group...) and advise A. Download and run scripts I. Unit: CVS A. Prep 1. Describe technology 1. Lay out objectives A. Checking out files A. Looking at history A. Updating files A. Generating patches A. Committing revisions I. Unit: Emacs Basics A. Prep 1. Describe technology 1. Lay out objectives A. Starting the program A. File commands 1. Open (C-x C-f) 1. Save/Save as (C-x C-s / C-x C-w) 1. Close (kill buffer) (C-x k) 1. Switch buffer (C-x b) 1. This window only (C-x 1) 1. Quit (C-x C-c) A. Editing commands 1. Keystroke compatibility - PgUp, PgDn, Del, Bksp 1. Delete word (M-d) 1. Undo (M-x u) 1. Kill line (C-k) 1. Fill area (M-q) 1. Select or mark region (mouse only, I'm a wuss) 1. "Copy, cut, paste" (M-w, C-w, C-y) 1. Search and replace for text or RE (C-s, C-M-s, M-%, C-M-%) I. Unit: Emacs and 'DocBook' XML A. Prep 1. Describe technology (psgml) 1. Lay out objectives A. Loading a 'DocBook' XML file 1. xml-mode (M-x xml-mode) 1. Parsing the DTD (C-c C-p) 1. Saving the DTD (M-x sgml-save-dtd) 1. Loading a DTD (M-x sgml-load-dtd) A. 'DocBook' XML keybindings 1. Delete tag (C-c C-k) 1. Insert a tag (C-c <) 1. Close (C-c /) 1. Delete to next ending tag (C-M-k) 1. Untag element (C-c -) 1. Change element (C-c =) 1. Repeat (close + open, C-c Enter) 1. Show context (C-c C-c) I. Unit: Entities and subdocuments A. Prep 1. Describe technology 1. Lay out objectives A. Entities 1. Create an entity 1. Use an entity A. Subdocuments 1. Create a parent document 1. Parse and save DTD 1. Create a subdocument 1. Load and use DTD 1. Use entity from parent document I. Optional Unit: Bugzilla - Moved to [DocsProject/DocumentationGuide/BugzillaTutorial BugzillaTutorial] page.

I. Optional Unit: Wiki

---