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
- If you have not read Diataxis, first read it in its entirety.
- If you have read it, skim the pages on How-to guides and the difference between a tutorial and how-to guide to refresh your memory and refer back throughout the process.
- Look at an example: this page, how to Compile and View Documentation Locally, and how to Troubleshoot Common Errors are all examples.
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
- Make it effortless to read
- Move Docstring Material to the APIs
- Minimize or Eliminate How-To Guides with a Single Step
- Remove Other Reference Material
- Follow the Guidelines on Cleaning Up General Formatting
- Look at the compiled .html!
Omit the Unnecessary
Jump the user right to a logical starting point in the code using #hide
or @setup
blocks.
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
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.
Preface each call to a new function with a hyperlink to that function's docstring so the user can find more detail
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.
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.
Move tables and lists of information into Reference pages and link to them instead
Follow the Guidelines on Cleaning Up General Formatting
Follow How-to Clean Up General Formatting.
Look at the compiled .html!
- 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