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: help.autodesk.com.
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"
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"
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 RevitForum.org 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".
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 RevitForum.org 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".
