Document WOGL

You’ve had some time to play with WOGL. Hopefully you’ve made some cool pictures, and started to figure out at least some aspects of how it works. Your job now is to write documentation for WOGL. The goals:

  • Develop your technical investigation skills; continue to learn how to learn about unfamiliar computing topics.
  • Develop your expository and technical writing skills.
  • Give yourself a useful technical resource for the forthcoming homework assignment in which you will refine and explain your own WOGL creation(s).

The entire class will work on documentation together, as a single shared project. Doing this collaboratively serves several purposes:

  • Knowledge sharing: What some students in the class understand can become things that everyone understands.
  • Division of labor: Some things are doubtless still puzzling to everyone in the class. (And on top of that, your nefarious instructor keeps sneaking in new improvements to WOGL on the sly!) Assign different subgroups of the class to investigate different things together, and then not everyone has to investigate everything.
  • Develop collaboration skills: Software development — and life in general! — is highly collaborative. Collaborating effectively with a team is itself a skill. It is a difficult skill one can improve over a lifetime of learning.

Planning

To write this documentation, we will need to discuss several things as a class:

  • How should the documentation be structured?
  • What do we already know?
  • What do we want to figure out next?
  • What tool(s) / platform will we use to write the docs?
  • Who is doing what?

I will lead an initial whole-class discussion on these topics, then give you time in class to break into smaller groups.

At the end of class

We’ll set up a shared document the whole class can work on together. At the end of class today:

  • Give yourself a task to do before next class. It could be:
    • writing an explanation of a specific thing that students in the class already understand,
    • investigating something students don’t understand yet,
    • verifying the work of other students (Does what they wrote match what you figured out?), or
    • suggesting edits to clarify or improve what’s already in the document.
  • Write down your task and put your name next to it.
  • Then do what you said you would do!

Our goal is to make documentation that’s useful to this class as everyone creates their original WOGL masterpiece. To that end, as much as possible, we want our documentation to be:

  • correct,
  • comprehensive, and
  • clear.

At the start of class today, the documentation we have is none of those things! Even when we’re done working on it for this class, it may not be perfectly comprehensive or clear, and it might even have mistakes — but we want to keep pushing toward that goal of being correct, comprehensive, and clear. (Utopia is a direction, not a destination.)

That means we need to do not just writing but also revision.

Let’s revise!

In order to manage the chaos of everyone editing at once, starting today there are new rules for working in the shared doc. In Google Docs, switch to Suggesting mode in the upper right of the screen:

Click the Editing Mode button in the toolbar, and choose Suggesting

You can now do four different things to contribute to the document:

  1. Add new information as a suggested edit.
  2. Suggest a change to clarify writing that’s already there, or to correct a mistake. You can do this either by:
    • making the change as a suggested edit, or
    • proposing the change in a comment if you think it needs discussion first.
  3. Review somebody else’s change, and either:
    • accept the edit, or
    • discuss it in a comment.
  4. Do new experiments and new research to fill in the gaps.

Note that all changes to the document now must be suggested edits. No more editing directly, not even to add new things! Note also that, at least for now, you may not accept your own suggested edit. These rules help ensure that this is a truly collaborative document that reflects consensus in the class.

Spend today doing the work of revising and fleshing out the document, and continue that work even as you work on your own WOGL creation.