TOC Driven Documentation

What

A common strategy used by engineers is TDD or Test Driven Development. In TDD, engineers write tests first and use those tests to help build their functions. This creates code that is easier to test and forces the engineers to consider what they are trying to build ahead of time.

We can apply a similar strategy for documentation. I use TOC Driven Documentation or TDD as a play on words here. The idea is that building documentation should be done intentionally with just as much thought put into documentation structure as you would put into coding structure. This applies to the overall document organization as well as to content pages.

Why

TOC Driven Documentation leads to better results. Thinking about the structure of your documents will help you present your information in a more organized manner and help those looking for clarity to find information faster.

How

In TOC Driven Documentation, ensure you are focused on building documents using TOCs as opposed to adding TOCs afterwards.

Step 1: Create Your Outline

Create an outline for your documentation first. Think about these questions as you create the outline:

• Who is your audience?
• What is your page about?
• What are the major parts of your document?

Your outline should have multiple headings and ideally have multiple levels of headings.

Step 2: Add a TOC Macro

• Add a TOC macro to the top and save your page.
• Review your TOC and the headings your created.

Step 3: Fill in Your Docs

Visit each of your headings and begin filling in the content.

Notice this is the first point that you are adding content to your docs.

Step 4: Review & Repeat

• Save so you can see your page.
• Read through your TOC.
• Rinse and repeat this review while adding content.
• Don’t forget to save periodically so you can see your TOC.