Thursday, October 24, 2013

Autodesk WikiHelp is not a Wiki Anymore

For the last month or so the Autodesk Revit documentation team has been transitioning to a new system for help documentation. When you click the help icon (?) on the Info Bar in Revit you'll find a new format and different help web domain:

You probably are well aware that a couple years ago they changed things to focus on a wiki based format that moved product help resources to a web based approach instead of the past Windows based .CHM help file format. This affords them an ongoing ability to deal with documentation. The results of their work appears online immediately and the very next time you click to access it. It's no longer tied only to software release cycles. It's certainly necessary to make documentation available as new releases become available but editing and additions no longer have to wait for the next release, nor do they have to consider issuing software updates just to distribute help documentation changes.

Wandering off on a tangent, people are often reticent to rely on help documentation or manuals, and not just for software. I'm sure there are plenty of reasons for that bad habit. Personally, many times the quality of the information is lacking so it's tempting to ignore what I don't find useful. Overall, I find that the quality of the documentation for Revit has been steadily improving. They revisit topics and that means ignoring the information means I miss those changes. That written, I still think the help documentation tends to explain things without useful context. For example, Levels have a parameter called Story Above.

This is the description for the Story Above parameter on the help site (with my snarky comments inline).

"From Revit Help"
Used in conjunction with the Building Story parameter, this parameter indicates the next building story for the level. (Implied by the name) By default, Story Above is the next highest level for which Building Story is enabled (NOT necessarily the relevant floor above). To access a list of all building stories above the current one, click in the field. (Ooh, I have to click on it??) The Story Above does not need to be the next higher level or building story. (Cool, anything else I should know?) If the selected level is deleted later or if Building Story is disabled, any levels with this level as their Story Above will revert to default behavior. (Still confused, why should I care again?)

That description does not really tell me why I should care about this parameter. It does tell us that it has something to do with this other parameter called Building Story. The first time I saw these I imagined that the stair tools might use them to guess more accurately what the base and top constraints should be. You may have noticed that Revit just assigns whatever the next higher level is to the top constraint. This means that if I've got an intermediate level for something like a stage platform that isn't really a building story on its own the stair tool thinks that's the next level instead of the next real building story.

If I happen to read further down in the topic I notice that there is a link for Exporting a Project to IFC. Fwiw, if I use search for Building Story the first result is also Exporting a Project to IFC. When I read about that I learn from this section:

"From Revit Help"
Split walls and columns by level allows you to divide multi-level walls and columns by level. When you use this option, Revit cuts the walls and columns by each level that is defined as a building story {my emphasis}. (See Level Instance Properties.) For elements whose base level is a non-building story level, Revit exports them using the next lower building story as their base level, with an appropriate offset. Revit only exports levels for which the Building Story parameter is enabled, unless no levels are defined as building stories. In that case, Revit exports all levels that are used as base levels for walls and columns.

It would be a LOT more "helpful" if the description for Story Above mentioned that our day to day work inside Revit won't be affected in the slightest by this parameter BUT if we export to IFC it becomes important. The same is true of the Building Story parameter. Features and additions like these that have very specific implementation but opaque intentions just add to the complexity of Revit. If I wrote the documentation I'd have started off with something like, "This is only relevant for Exporting to IFC", if in fact that is true. If it isn't then what else are they not telling us?

Back to the subject of the help format. So far so good. It looks pretty good. The search results provide a portion of the subject to help see if it is relevant enough to focus on. The speed is pretty good. I don't like it's preference for Internet Explorer which I only use when forced to. {Per Jeff's comment this is defined by the browser setting in the Revit.ini (there is one for default and one per user profile) and we can choose which browser we prefer.}

At the moment the lack of access to a unique URL for each topic is annoying. I've read that this is something they are working on so eventually it won't be an issue. For now we have to rely on the Share widget to access one of the social networking share options.

I find that Twitter and Delicious are the only two options the show the unique URL without having to log into the social site first.

This means a Twitter account isn't required to access the URL so I can share it with someone else. Just be careful not to include the "Reading:" portion of the URL information (see the image above). As a member of online Revit user groups like AUGI and I often want to share a link to the help documentation with another user to answer their question. It's tedious to do it at the moment but eventually it won't be.

Then again it's this kind of subtle "miss" that make me wonder what goes through their minds as they prepare to unveil the next great help concept from Autodesk. Maybe they are jaded themselves about how much people actually rely on their work? I hope not. If unique URL's were another week away then perhaps holding off a week would have made for better first impressions? Sometimes I think Seth Godin's "Ship it" is misconstrued to to mean ship it regardless of fit and finish and readiness.

If you rely on Google searches to find help documentation it will take some time for Google to index their new help site. Once it is indexed we should be able to rely on Google searches too. I read that the documentation for older releases is being transitioned to the new site format now so if you are looking for 2012 help you'll be directed to 2014 information for now. The standard line is offered, "We apologize for any inconvenience".


JB said...

Great OpEd. Completely agree.
Plus I appreciate that you taught me something during that rant! Thanks

On the note of the Help page not having a unique URL, I found that if you can manage to find a link from one topic to another (see parent topic, or related tasks) and you can copy link address.

Hope that helps

Jeff Hanson, Autodesk Learning Content said...


Thank you for taking the time to visit our new Autodesk Help site. I am glad to hear you are finding the search tool quicker and better suited to helping you find the information you are looking for. We have worked to make the search tools on the new site faster and more robust so it is good to hear that the work is paying off and you can see the difference. I am also glad to hear you feel the quality of the documentation overall has been steadily improving.

We do understand that the lack of a shareable URL is annoying. We are working on a fix for this and hope to have it resolved soon. This new framework allows us to make frequent updates and improvements to its functionality while maintaining the help content and user comments.

Concerning the “preference for Internet Explorer,” Revit uses your system default browser unless you specifically override it in the Revit.ini file as documented here:

As for your observation about the “Story Above” parameter: we realize context is of value in the help documents, and there are examples (this being one of them) where the body of the article is not giving the full context without reading the additional articles linked. This is also an example where the comments section can help our team make articles better. We can take feedback like yours, modify the help topic, and republish the content. We hope that as users engage with the content and give us feedback via comments, we can continue to build a better help system.

I will work with our Learning Content team to edit the topic you mentioned so it provides the context required to make it more useful.

Steve said...

Thanks JB and Jeff!

Too often help documentation reads like this:

Help Button - If you click on the help button it will open the help window.

I have met people who need that advice too but generally we infer that result because there IS a button.

It's far more informative to explain why a help button even exists. In the case of the examples in this post those two concepts were introduced to support IFC, at least primarily.

Paying respect to that origin is critical to deciding whether I should care about the setting at all. I can imagine two Revit managers arguing about which settings are correct when neither is actually exporting to IFC. So doing nothing is just as valid as worrying about setting them deliberately.

Thanks for listening!

DaveP said...

Ages ago, I worked on on old UNIX system (text only). It had a number-based menu syetem, and every single one of the menus had:


When you typed 9, the following message appeared:

Type in the number of the topic
then press ENTER

Thanks for being SO helpful, HELP

Paul H said...

Thanks for another great article, and helping to explain why we do not use the revit help system very often.

I remember the AutoCAD documentation from the 80's and 90's was incredibly thorough (when it came in volumes of books) in explaining WHY a command existed and how to use it in a work flow. Revit is missing this.

Using Revit is a process, and understanding why a command or setting exists and how it fits in a work flow is just as important as what it does.

Unknown said...

Hold your mouse cursor over a command in the ribbon hit F1 key.

Jeff Hanson, Autodesk Learning Content said...

As a Thanksgiving gift the sharable URL issue has been resolved with Autodesk Help. you should now be seeing the full shareable URL in the address bar of your browser. I had to clear my browser cache to make this work.

The other issue about the story above parameter was also fixed a couple of weeks ago.

I wanted to wait for the URL fix before I posted an update.