Redocumenting using Diataxis

my takeaways

These are my takeaways when I studied the Diataxis framework. They represent how I, personally , internalized some of the ideas there. You should definitely study the framework and create your own mental models, but knowing how I've interpreted them might help my re-doc make more sense.

the mind-map outline

diataxis

  • how-to guides
    working practical docs
    • characteristics
      • problem-oriented
      • goal-oriented
      • walk reader through steps
      • solve a real world problem
      • recipes
        • tutorial is beginner stuff
        • how-to answers a more obscure question only asked by experienced users
    • construction
      • assume knowledge and experience
      • focus on results
      • solve a particular problem
      • don't explain concepts
      • allow for flexibility
      • leave things out
      • name guides well
  • technical reference
    working theoretical docs
    • characteristics
      • characteristics
        • describe
        • does not explain
        • does not instruct
        • austere and to the point
        • basic description of how to use the machinery
      • construction
        • structure around the code (or what's being described)
        • be consistent, like a dictionary
        • only describe
        • be accurate
  • studying
    • practical
      • tutorials
        • characteristics
          • learning-oriented
          • leading the reader by the hand
          • goal: complete a project
        • good tutorials
          • learn by doing
            • concrete steps
            • not abstract concepts
            • minimum explanation
          • get the user started
          • things must work as described
            • reliably repeatable
            • only the necessary steps
          • results must be immediate and visible
            • you have just
            • describe results
            • add some admiration
    • theoretical
      • explanation
        • characteristics
          • understanding-oriented
          • discussion
          • clarifies
          • illuminates
          • not defined by any system vector
        • provide context
        • discuss alternatives
        • don't instruct
        • don't provide tech reference
  • overview
    • structured by these four
    • distinct modes of writing for each