Reflections on re-writing tutorials

The following was written by Marcel Dubois, Lead Technical Writer for Autodesk Revit Structure on the AEC User Experience Technical Publications team.

When we began planning for the 2010 release, one feature in particular was always at the top of our priority list; the new ribbon UI. We knew early on that this task would require a total rewrite of over 600 pages of the existing tutorials, and that the work would be delayed until after the UI design was stable. This presented us with additional challenges including a shorter window in which to update the documentation. We were faced with some tough decisions that revolved around the unknown variables of the ribbon design and trying to estimate its impact on our overall schedule. Based on the added time to learn the new UI, I estimated that it would take me at least two days to adapt each tutorial. After starting, I soon realized that my estimates were too high. Once I figured out the logic of the ribbon layout, I was able to convert each tutorial in less than three hours (instead of the original two day estimate.) This included validating each step and capturing new images in the drawing area and dialogs. The new tutorials were completed ahead of schedule and are based on a more realistic user workflows.

For those of you re-writing your own documentation to fit the new 2010 UI, does this match your experience? If not, what in particular about the new UI is making it difficult to update your documentation?

_tom

Comments

[Chad]

I've written plenty of office Revit documentation in the past, and am currently in the process of writing more. Even though the new procedure documentation I'm currently writing is for 2009, I am still referencing 2010 to take note of future changes.
From what I can tell, there really isn't any change in ease. You take screenshots and add text.

If anything, the process in 2010 would be longer because of the increased number of UI permutations.
In 2009, the large number of fixed toolbar buttons meant that you could use less screenshots because there is more consistent information on the screen at the one time.
In 2010, you will have to take a screenshot for ever single change in the workflow due to the jumping around it causes.

It's not that Marcel completed his task quicker than expected, just that he over estimated how long it would take in the first place, as he indicated.

"The new tutorials were completed ahead of schedule and are based on a more realistic user workflows."

Hmmm, sounds like this article is more about validating the UI (marketing), rather than asking for documentation opinions.
The UI is here to stay, we understand that, so asking for these opinions has little to do with how we would like to see the UI improved.

After all, how we document should have far less influence on UI design, than our more direct and very specific UI requests. You're asking the wrong questions.

[Anthony Hauck]

First of all, yes the UI is here to stay. But does it have the potential to evolve as we continue to work on it? Yes. Second, this blog is about the entire user experience, not just the user interface. This includes the user assistance materials such as tutorials. The intent of this post, and all of our posts, is to generate a conversation with our user community. Re-writing in-house documentation has been expressed as a major concern. So I thought I would share one of our experiences and find out what others have experienced.

[Anthony Hauck]

That said, if you are interested in having a conversation, I will ask a question: are screenshots of the UI absolutely necessary? In our tutorials, we include screenshots of the view and resulting work, but use Tab -> Panel -> Command name text format to indicate state instead of screenshots. This is primarily due to our need to localize to many languages. However, it allows the documents to be somewhat lighter weight with the focus on the result instead of the UI. Thoughts?

[Chad]

"are screenshots of the UI absolutely necessary?"

From my experience with training beginners, yes. Unfortunately, there are always users where you have to spell everything out with in-house training manuals and standards, so you have to aim for the lowest denominator.

The Ribbon is going to make spelling these things out even more important now that there are tools which are grouped together (i.e. drop-down arrows), can rip Panels off and also hide the Panel Titles. These are things that make using just text an issue.

Because the UI has become more complex to traverse, so must the documentation to keep up with this. It's no wonder why this is a concern.

[K]

I completely agree. You have to design your documentation to the lowest common denominator which unfortunately means having to create step by step with pictures along the way. As far as the help menus and tutorials go, from my experience there is a reason why most users don't use them the majority of the time. Because they don't understand it or can't follow it. Designers are visual people. They need a pretty picture to help guide them. If the help menu and tutorials were a perfect resource we wouldn't need people who write books about Revit because everything would be clearly explained already.

[Chad]

Just one more comment. I still believe that the Revit Tutorial documention is the best tutorial source I have seen for any software I have used.

Because of this, when I train a new user I get them to sit down for two solid days and get them to go through as much of this book as possible. This does two things;
1. It means that they are doing it on their own company time, and not taking up 2 days of resources from myself or another Revit user.
2. More importantly, there are always frequent questions from the user about particular parts of Tutorial guide. Mostly, because they have issues finding a tool or tool options. This overall process gives me an indication of where their Revit weakness' are, and can be built on after the two days.

It's because of point 2 which tells me that even Autodesks own Tutorials (as good as they are) still don't go into enough depth to explain a process for a beginner.