Writing walkthrough guides and technical documentation is more about the flow that you are describing rather than the actual writing itself because you are wanting to explain the process, not to write the next best seller on the NY Times book list.
But there is still a little creativity that you need to make the walkthrough interesting to the reader.
Although I have noticed that there are a number of different variations of the way that people want to have walkthrough guides structured depending on the audience.
In this walkthrough I will show a new Compose feature within the Author Tools template that may help a little with this problem.
I usually use a pretty simple structure while writing my walkthroughs. For example, here is an example blurb that I write for one of my guides that explains how to assign a Customer record a Type:
The first thing that we will want to do is set the type of customer record that we want to create.
Customers are configured either as a Person or as an Organization with their own specific naming format.
To do this, click on the Type dropdown list and select the Organization Type from the list
In this example we will set the Type to Organization.
Now we have set the Customer Type.
For example, here is the storyboard slide that I used for that example
And this works pretty well in most cases.
But there are some cases where you may not want to show all of the information that I have in the text of the slide.
For example, if I wanted to create a version of the walkthrough that shows just the step description and the sample data that I need to enter then I would have to create a new version of the storyboard and then cut up each of the text blocks and change the detail.
If you dissect it then you will see that it has these components:
Introduction: The first thing that we will want to do is set the type of customer record that we want to create.
Detail: Customers are configured either as a Person or as an Organization with their own specific naming format.
Action: To do this, click on the Type dropdown list and select the Organization Type from the list
Example: In this example we will set the Type to Organization.
End: Now we have set the Customer Type.
And within that structure there are also subcomponents that are useful, like:
Action Shorthand: Select the Customer Type
Example Data: Type: Organization
Not all storyboard slides are this detailed, or have all of these components in them, but it is a good example of a structured step with a lot of detail.
What I need to do though is extract all of these components out and then pick and choose when to use them.
To solve this problem I created an Advanced Storyboard template that I can use to extract out the different parts of the text block broken out into the different components.
This allows me to move the Text content into its corresponding text block and also create some additional variations of the instructions for the Shorthand and Data blocks.
Now that I have broken out all of the text into its component blocks, now want to use these to create my new variations of the final slide text that I will be using to create my documents from.
To do this I have added a new function to the Author Tools called Compose.
This allows me to select from a number of different composition templates that then specify how I want to build up each of the text elements in the storyboard – Subtitle, Caption, Text and Notes.
If I select the Guide template then this will copy the Shorthand to the Subtitle, the Data to the Caption, build up the Text from multiple different blocks and then also add a few more of the blocks to the Notes section.
If I change the Composition Template to the Lab template and then recompose the slide then you will see that only the Shorthand and the Data is added to the Text, but a lot of the description is added to the Notes section.
This is the perfect format for Presentations because the notes will show up in the Speaker Notes section.
If I change the Composition Template to the Exercise template and then recompose the slide then you will see that only the Shorthand is added to the Text, and the Data is added to the Notes.
This is the perfect format for hands on exercises because it is short and concise.
To see this in action, I have expanded out the Storyboard from that one slide to the full walkthrough with all of the different steps broken out to use the composition blocks rather than having all of the data in the text and then built the content of the text so that it has the Guide format.
If I switch to the Write tab and then select the Recipe template, then I can create my output document using this version of the content.
This will create my Recipe style document with all of the text giving me an instructional document that everyone is able to follow.
Now I will return back to the Storyboard and recompose the storyboard text using the Lab format.
When I recreate the Recipe document based on this version of the content then all of the steps are listed out for me showing the Shorthand and Data components, but no detail.
This is a great summary document for the expert users.
Finally, if I will return back to the Storyboard and recompose the storyboard text using the Exercise format then it is even more concise.
Bit one thing that I can also do here is update the template details and change the components that are being used to build the slide. Here I added the Shorthand to the Subtitle, and the detailed text to the Notes.
Now when I create the Recipe document it has each of the Steps listed out with the data from the step as detail. This is an even better version of the Exercise in this case.
The decomposition of the Storyboard steps may seem like a little bit more work as you are writing your walkthrough guides, but it is worth it.
It makes you think a little more about the structure of the content that you are creating, and also then allows you to create variations of the walkthroughs for different purposes.
If you want to create a Presentation then you may just want to have the key information showing on the slides and not have the detailed text.
If you are creating a detailed Walkthrough guide then you may want to have more explanations for the screen shots than you would normally have to help the reader guide themselves.
If you are creating Hands on Labs then you may want to skip the detail, but have the steps and shortcuts in the document for easy reference.
If you are creating Student Exercises then you may want to have the step but no data so that you can provide that as a separate document.
And now we can do that through the Compose function.
How cool is that?
Share this post