What is your strategy for instructional content (steps/tasks/tutorials)?


#1

How do you approach writing instructional content in your documentation? Here are some things I’ve tried throughout my career, listed in order of worst to best:

  • One task (set of steps) for each GUI screen (yuck)
  • Pro: Easy to tell you are complete, takes very little brainpower to “write to the GUI”
  • Con: Really unhelpful to readers; they want to get something done, not see everything you can do on a particular GUI screen
  • One task for each button in the GUI (yuck)
  • Pro: Easy to tell when you’re complete, everything that can be done is documented in some way
  • Con: Still not aligned with user goals; a user likely must reference multiple tasks to achieve their goal
  • One tutorial/scenario for each user goal (a thing the user wants to do)
  • Pro: Closely aligned with user goals, and therefore probably the most helpful approach
  • Con: Very expensive to produce, can be difficult to know what user goals really are, it’s hard to know when you’re complete, and some parts of the product may not be “covered” with instructional content

What is your strategy for writing instructional content?

  • Have you tried any of the approaches I listed above?
  • Have you done something else? If so, please explain!
  • Do you have a mix of these types of content or just one?

#2

I focus on task-driven documentation or “user story” documentation. While it will never be complete, you can prioritize to cover your more common user stories first.

Also, you can link off to short articles that cover common tasks to reduce repeating the same instructions over and over in different articles.


#3

I work with end-user docs, so I don’t know how helpful this is for the majority of folks here, but we have several doc types for different article/user goals. Commonly, you’ll see a reference doc that describes UI, along with a separate (or various) goal-oriented procedural.

For example, we might have a very very simple article for new users like this Dashboard article. In the List Growth section, there’s a link included to this signup form article.

The signup article has a combo of an overview of the Form Builder UI and additional options, as well as procedural steps to access the builder and customize forms.

In looking for an example to share, I found many things to improve on these two articles, but there it is!


#4

@ediff we have similar article types that achieve different goals. For example:

I think goal oriented tutorials/tasks are the right way to go. My struggle is that I’m a completionist–it really bothers me if parts of the product aren’t “covered” by task documentation. In reality, that’s probably silly because users don’t need a task for every possible action (To delete, select the object, then click Delete). Instead, they need to know how to achieve their goal, solve their problem, etc.


#5

@davebraasch
This is something we’ve struggled with as well. We have another doctype called “Quick Answer.” Originally, they were created as a catch-all for what were very short/focused articles that we felt didn’t merit an entire article page. That’s not really working, though.

We want to retool to function slightly more as an FAQ or as very simple mini-tasks, such as how to delete something, as you suggest. Unfortunately, we haven’t quite figured out how might best benefit users. Will they’ll know where/how/when to find these QAs in lieu of full articles? Do they need to be pulled into the app itself? Pulled into full articles as needed? But it’s something we are playing around with.


#6

@davebraasch , I like Joao Fernandes’ solution, in his talk on User-Story driven docs – https://www.youtube.com/watch?v=MRnZFVCirQM