Write a How-to Guide

A How-To guides a user trying to accomplish a certain task in their work, or address a problem or series of linked problems.

Prepare

Follow the Do's and Don't's

The Diataxis How-to's page should be your main reference as you write, but in addition, use these guidelines to ensure we follow Diataxis and avoid common pitfalls from previous versions of Sienna documentation:

Omit the Unnecessary

Do

Jump the user right to a logical starting point in the code using #hide or @setup blocks.

Do

Configure the logger or load/build a System that returns very few log statements. Use semi-colons at line ends to hide return statements if need be.

Make it effortless to read

Do

Split code examples into ideally 1 (to 3) lines ONLY, with a short preface to explain what each line is doing, even if it's obvious to you.

Move Docstring Material to the APIs

An issue with earlier versions of Sienna documentation was basic reference information located in pages other than the APIs. See how-to Organize APIs and Write Docstrings if needed to make that information easier to find.

Do

Preface each call to a new function with a hyperlink to that function's docstring so the user can find more detail

Don't

Include digressive details about different keyword arguments or versions of a function.

Minimize or Eliminate How-To Guides with a Single Step

A how-to guide has a sequence of steps – if your guide only has a single step, ask yourself if you are compensating for a lack of information in the API's.

Do

Move how-to guides with a single function to being Examples in that function's docstring. See Writing Documentation.

Remove Other Reference Material

Particularly when editing existing pages, watch out for other Reference material.

Do

Move tables and lists of information into Reference pages and link to them instead

Follow the Guidelines on Cleaning Up General Formatting

Look at the compiled .html!

Do
  • Compile the how-to guide regularly and look at it
  • Check all code examples gave the expected results without erroring
  • Check for length of the code examples and iteratively adjust to make it easy to read