Structuring a Document

A flat list of steps works fine when the task is simple. As things get more elaborate, though, you'll want to organize the work. Suppose you want to construct a bypass so people at A can get to B very quickly and people at B can get to A very quickly.

Start with just the planning steps:

    1.  Complete survey paperwork
    2.  File documents in the planning department
    3.  Ensure the "Beware of the Leopard" sign is still hanging

That's a perfectly valid Technique document. But there are really two different things that need to be done: the paperwork done long in advance, and what happens on the day the bulldozers arrive. We can mark these with sections:

I. Preparations

    1.  Write the traffic impact assessment
    2.  File documents in the downstairs planning department
    3.  Ensure "Beware of the Leopard" sign is hanging to draw attention
        to the locked filing cabinet containing the plans

II. On-site

    1.  Ensure all workers have hard-hats
    2.  Unload bulldozers. Verify they are painted yellow for safety
    3.  Demolish house

Any non-trivial step can itself be broken down. Unloading construction equipment is hardly a single action. We can decompose it into substeps, indicated with lowercase letters:

    2.  Unload bulldozers
        a.  Drive to address of the almost entirely unappealing squarish and
            squattish house at end of lane
        b.  Unload demolition equipment from trailers
        c.  Verify bulldozers are painted yellow for safety

The substeps must be done in order, and step 2 isn't complete until a, b, then c are. Only then can you go on to step 3.

A valid Technique document is either a bare series of steps or a procedure. Here the document as a whole is given a procedure declaration to name it and show its starting point. We can also wrap the content of each section in one or more procedures, giving them names of their own.

build_bypass :

I. Preparations

file_planning_documents :

    1.  Complete survey paperwork
    2.  File documents in the downstairs planning department
    3.  Ensure "Beware of the Leopard" sign is hanging to draw attention
        to the locked filing cabinet containing the plans

II. On-site

demolish_house :

    1.  Ensure all workers have hard-hats
    2.  Unload bulldozers. Verify they are painted yellow for safety
    3.  Demolish house

Each procedure can have a title and description and other context which we'll learn about next.