Related Posts with Thumbnails

« Last Command | Main | Modeless »

July 23, 2009


Feed You can follow this conversation by subscribing to the comment feed for this post.

A couple things you describe what the different wall functions do, but what are their purpose? For schedules?

Also it states

"■ Foundation - wall foundations are members of the structural foundation category. The structural base
of a building that provides stability and rigidity"

This isn't true wall functions that are set to Foundation aren't part of the Foundation Category, they are still part of the wall category.

It's a step in the right direction, but the terminology used is inconsistent, which leads to potentially confusing moments for those who don't already know what is being discussed (ie the target audience).

For example, the first sentence enumerates the functions of walls, but then the second uses the term structure in an ambiguous way. A reader might wonder if that is meant to be a synonym for function, somehow.

Another example is the definition of simple and compound walls. Standardized settings isn't what makes a wall simple, is it? Can't standard walls that we all use be compound? This is confusing, as is the term component defining compound walls. Since component is a specific term in Revit, using it in a slightly different manner is not so good. Either provide an example in-line ("such as 2 x 4 wood studs and 5/8" gypsum board."), or pick a different term ("elements"? "building materials"?).

Continue the theme throughout. Keep striving for clarity and conciseness. Don't define architectural terms ("The structural base of a building that provides stability and rigidity"). Do tell me why Revit behaves the way it does.

I'd be happy to provide feedback on any section of documentation.

Please Add more graphics with your explanations, a sketch is worth a thousand words, it is time to explain Help in a more interactive way with flash....or more graphic real life examples which makes sense for all of us

I agree with "mo". Kudos to Joel for actually reading the whole thing, I gave up after the first page, there were no pictures. ;)

In all seriousness. Yes we're all "adults" but have you folks done learning research on architects and interior designers? The majority of us are biased as Visual Learners (that's why we're architects!). An engineer of some type might appreciate a nice tombe on their design software, but I guarantee that two solid pages of text (no matter how informative) will turn off most day to day A/I users.

I realize that you would probably prefer to stick with an M-Soft CHM or PDF, but there is something to be said for a more interactive help system. Where information expands or becomes available as a person digs deeper, then they don't realize how much they're reading, also graphics to explain it all! Describing a location line takes how many lines of text, and even then a user may not understand, versus a picture, diagram or video.

I also beleive you need to consider the audience. Is your audience really going to know nothing about Revit? Just about every firm I've heard of adopting Revit, invests in some type of training. While it is important for a help system to address all aspects of a program, I beleive your help really needs to be tuned in a way for users to support themselves, based on the assumption they know something, or at the very least were taught. You need to find a way for users to get answers to their questions, not give them a 30 page manual about walls, and expect them to read, process, learn and answer their question so they can keep working. No one reads manuals, did you read the manual that came with your cell phone, microwave, dishwasher, camera? How do you learn how to use those tools? Why do some mfr's products succeed, where others fail? You've got the market cornered, we're stuck, so you're not going to fail at this point due to lack of usability/learnability. Therefore, at least work to improve how our users answer their questions.

While architects (and I am one) and interior designers tend to be visual learners, we can all read. It is easier for me to get someone to read two pages that are very well done, than to have them process fifty pages of screen shots, and really digest the content. Good diagrams, on the other hand, are well worth four paragraphs of dense text. Bad diagrams (the stuff in the "Architectural Workflows" section of the current docs) shut people right down.

Regarding audiences, perhaps "no one" reads manuals, but everyone asks their resident expert. Where does the expert get their expertise? Where do they turn when they are asked something outside of their expertise? The manual! And staff, once trained, need something to reference back to, to jog their memory, deepen their expertise, and learn topics not directly covered by the training.

As someone who DOES actually read manuals, I desperately want them to be good. I want a reference manual that is the definitive resource. I want to know why things work the way the do so that I can figure out how to deal with the thousand-and-one situations that the docs don't (and can't) cover.

Ok, can you tell by now that I care about documentation, and actually try to read it:) ?

Joel, I'm not against you, and I realize I was making some sweeping generalizations in my previous statement(s). However is the Help System supposed to be a technical software manual, or is it supposed to help users? I can usually find what I need in the current help, but that does not make it attractive or useful to my day to day users. Something that works, and results in useful information (Google, Kayak, AUGI) will get used. I also agree you have to balance image with text, but when I see two solid pages of text with a couple of icon images, and that is presented as the "example" of 30+ more pages of information... you've got to wonder.

I for one, tend to read manuals after the fact, I experiment, play, research. Therefore for me especially, 30 pages of information about walls is not going to be so useful, particularly if it is not well indexed, and there is not a useful way to move through the data in a non-linear fashion.

I think that is perhaps the critical insight, this is not a linear issue, particularly when someone wants help or is trying to solve a problem.

A friend said this to me "The problem is that technical writing is really hard, and a difficlut skill to develop, and expensive. But most mfrs just assume the engineers who made whatever widget can write the manual. NOT TRUE! You need somebody with the mind of an engineer, the heart of a poet and the empathy of a social worker to do it. And those people are rare."

If they want to write a manual too, fine, but that is not a help system, and I for one am more concerned about useful help information that I can point users to. The manual is nice, but it will likely gather a lot of dust, except for people like you and me (on occasion).


I appreciate the comments, especially this part: " this is not a linear issue". We're on the same page.

What does a user hope to get out of application help, if not reference material? If help consists simply of procedures to accomplish discrete tasks, where is the reference manual? No one will ever completely document how to do every task possible, so we need to have a good handle on why and how the software behaves. Trial-and-error is great, but only goes so far; I'm searching for deeper insight.

I keep an old copy (hardbound!) of Autocad's Reference Manual for release 12 at my desk, simply because it is well done, and still germaine to 90% of the Autocad work we do. For Autocad, the seperation of User Guide / Help System, Reference Manual, Customization Guide has worked pretty well, but has been eroded over time, as Autodesk has not kept up the Reference portion of the package (it's now simply a Command Reference, listing commands and variables, and brief discussion of each, all too brief for new content).

I've read a LOT of technical writing over the decades, and have seen the quality of docs provided by app vendors decline dramatically. Yes, it is hard. Not to be undertaken by marketing staff, nor software developers. None the less, I feel that it is absolutely essential for any product hoping to exist and thrive over the long haul. Modeling reality (via BIM) is an undertaking requiring great depth, full of nuance. Also, finding a good editor for a technical books is every bit as hard as finding good authors.

I will also add that I am a devout purchaser of third party technical books, but for the application-specific realm, the author being an outsider to the devs inevitably limits the depth that can be achieved. Most of those books are doomed to treat the subject superficially. And the Revit books are a good example of this: ok for the beginner, but nothing with depth, no one willing to address the thornier issues.

I guess I'm thinking in terms of something like Sketch-Up, which has had great success with intro lessons that directly integrate with the product, and videos that address task based activities of a variety of skill levels. This does not address your concern about digging deeper and fully referencing all commands which I also beleive is important. I have always found (in previous versions, have not looked a newer stuff) Adobe's help to be fabulous, filled with images as well as the technical details, and making it easy to quickly learn a task, but to also follow-up and dig deeper. I think, as you said, this is where good authors and editors come into play. I also agree that the technical team can bring a deep knowledge to the table, but that has to be balanced with practical information with regards to how you apply the software, because at the end of the day, users need/want to know how to use the software first, during that process, they need to learn how the software works in a technical way. I appreciate your desire for the deep dive, but I would rather see time spent on a help system that will be beneficial to the majority of users, which at this point does not include me, but includes the people I support and help.

Wall Functions
What are they good for
cant Schedule them
cant Filter them.....
why should i bother.....
So where is the conceptual explanation?

I realise that the above example is an abridged version but am not sure how we can evaluate it without the full version.

If it is "conceptual" then there needs to be an explanation to go with the information: -

Walls Overview:
What is the difference between Interior and Exterior walls, apart from the obvious. Do I really need to have two sets of wall types interior and exterior, what if I use an interior as an exterior, what is it going to do to my model. Why do I even need to specify interior walls, if the wall is inside my exterior walls then shouldn't Revit know that it is an interior wall?

Soffit, how is a soffit a wall? You need to provide examples of the non-standard real-world use of walls.

There are lots of instances when I can't get a wall to do what I want it to do and what it can do in the real-world. I would like an explanation of what the limitations are.

Why can't I load a family, say a standard lighting truss (theatrical), and then rotate it in any direction, like the stage-hands do on-site? Again, if this is a limitation then it needs to be in a conceptual manual.

It would be useful to provide more in-depth information on items/methods of achieving an outcome that isn't a normal use of a particular tool.

Video or flash would be my preferred method of learning as I do not want to sit and read pages of information. Being shown how to do something seems to sink in quicker as I don't have to think or try and interpret what the text says. But it's not everyone's cup of tea and so therefore we need both types.

I agree with Joel that the terminology needs to be 100% consistent. However, it also needs to match the words in the software - for example wall "function" and "Structure" do match the software but are extremely ambiguous, particularly as the word "function" is also used to describe the wall layer function once you get into the wall structure! Not to mention "structural usage". You need to find a way to explain these terms clearly as the manual progresses.

If the first 3 pages are an example of the rest, it is a worry. However, if the intention is to expand each section then it may work. The section on "functions" needs to explain why or if it matters which one you use - I suspect that many Architectural Revit users never change the default wall function and are none the worse for it (Structural may be a different matter). The section on Location lines is almost incomprehensible without diagrams.

The section on sketching wall shapes is completely confusing - what message is it trying to convey? Does it mean I have to somehow go into sketch mode?

This manual needs some serious editing, but before that it needs a clear "structure" and sequence. As a user, I want to read about simple day to day things like how to place and modify a wall, then learn about location lines before I even think about defining a wall structure or its function.

Thanks for the feedback! The User Assistance team is reviewing all of your comments - especially the specifics about consistency, terminology and conceptual clarity. I have posted the full chapter (see original post) for those that are interested in delving a bit further.

Here is a way-out idea that another Autodesk product team is experimenting with: wiki help. What if the help docs were posted in a wiki format where users could add, edit, and discuss? Kind of like AUGI forums, but more structured and focused on enhancing help ? Just a thought...

A well moderated wiki would be very cool. We use a wiki internally and I love it. However, you would I beleive need a staff member committed to maintaining the portion for each Revit platform, and maybe an overall admin. Wikis are very powerful, but they require a dedicated group who constantly care for and feed it. Also, it seems so easy to talk about structuring the information, but we have not come up with a format we're 100% happy with yet. We have been very successful with our Education Curriculum, Revit Content Development Tracking and Software tracking, however the portion that is simply about working with and using Revit day to day is still not as successful as I would like to see it. You also most definitely need a person with the traits I described above to help manage a wiki. Our favorite (after a thorough review, and what we use) Confluence by Atlassian (great stuff).

here is an example I just got this question:
How can I create a fake View Title to reference the Sheet number and show the Detail Number but the Title would say NOT USED to eliminate a detail from a sheet and keep the numbering order in the sheet.
So I have to answer or create this thing but where are the related explanation and HELP?

As others expressed... I agree that that help doesn't help me understand what revit expects of me (which is a kind of backwards way of looking at it IMO I should expect Revit to do what I want.) For instance... I originally set up our foundation wall types to use the foundation property. Well the normal workflow for walls is pick a view, pick a wall, set the height, draw away... BUT when you pick a wall type of foundation, you're now supposed to set the depth (down that is... can't use negatives to go up which is confusing in itself anyway) but i'm on the foundation plan set to the bottom of my walls and I don't want to go any further down and there ain't no more levels further down. Can't pick a level above either as revit says thats a no, no. "WHAT'S UP WITH THAT?!!!" So very frustrating trying to explain that to new users, in fact I gave up and just defined all my foundation walls as exterior to keep consistent workflow. I could have just told them to draw their foundation walls on their first floor plan, but you can see what you drawing (without messing with view properties) and it doesn't make logical sense to draw foundation walls in a first floor plan view.

I'm sure the original intent with a foundation wall type was well intended, but it just doesn't flow or work well for us, besides as others have said what's the point of defining those properties if they're not used or visible elsewhere.

The help file should at least explain What revit does or is "thinking" when each of those types is used.

Regarding the way-out Idea...I'm personally not a big fan of wikis. I've used one for a software development project and felt that it just got in the way of getting stuff done. If thinking about going the wiki route, why not have augi like place where help is stored and maintained by autodesk, you could add videos made by users or autodesk and have them also hyperlinked into the help documentation, so that one may search help for something particular and then they could read help or watch video (people learn best different ways). I agree that software help files should be brought into the technology age of communication, but I'm not sure there isn't a better format than wiki style.

I agree a poorly executed wiki is not useful.

It would be interesting if it were actually part of AUGI, and not Autodesk, but there were some sort of compromise on administration and management, such that Autodesk would feel "safe" about publishing their "official" content while allowing a much tighter integration with "unofficial" content. How many "simple" questions on AUGI could then be answered by simply referencing a link (which we already do with threads), or doing an "include". Screen shots and videos all available to "insert" or reference as needed to explain a point. It could be quite powerful. But it has to be properly executed.

A wiki is a bad way to go if the users are expected to create the documentation. A wiki seems best in situations where experts can create pages, and then other experts can augment it. Distributing creation and peer review in one fell swoop.

I don't feel that this is what the Revit docs really need, but on the other hand, a way to have docs that Autodesk can easily add to would indeed be useful. Publication of an entire document is a huge effort, and errors can creep in. A wiki would allow easy corrections and additions over the life of the platform. Note that it's life must be longer than a single release, but updating for a new release would mean that Autodesk would need a parallel wiki during development, and a way to preserve user-made changes that would still be pertinent that were made in the overlap time.

No matter what, you have start with quality documentation, the more definitive the better. An improvement over a wiki would be a public way for people to ask questions and have them answered by knowledgeable Autodesk. Ramping up support's participation in AUGI would probably be the best venue for this, and would help a lot if the answers were thorough and accurate.

Side note: the foundation wall situation touches a nerve with me that too many corner cases are created by Revit. This makes it more difficult to grok and thus less intuitive. If Autodesk wants to make Revit easier to use, pitch the ribbon and focus on tool behavior. The hardest things for new users to learn are NOT the interface, but all the variations of every tool. Mirror resets its options, but trim doesn't. Foundation walls are created differently than other walls. Some symbols can be modified, but not others. You can't change the lineweight of view boundaries. The list seems endless.

I agree with Joel, a Wiki is not the way to go. There are too many out there with wrong or inaccurate information.

Who would maintain the Wiki and would Autodesk correct misinformation in it. I have seen many questions asked on the AUGI forums where the users give the answers but they're not sure if the answer they gave was correct or they are not sure why Revit won't do something. I have yet to see many of these answers confirmed by anyone at Autodesk or any other answers offered. The only people that I have seen respond have been Scott Davis and JeffH. So how would a Wiki be any different.

There was a time when nearly everyone at the Factory would offer advice on the AUGI forums to correct misinformation but not any more.

If this is the future direction that Autodesk is taking, by not participating in the forums, then there needs to be better documentation as I mentioned in my earlier post and as Joel mentioned in terms of all the tool variations and methods of achieving your outcomes. In fact, regardless of the direction of Autodesk there needs to be better documentation.

With regard to the tool variations or different uses of a tool, how many times have we been offered advice on using the railing tool to create an “x”. Who would know to use the railing tool to construct an item that is not a railing? Why on earth should we use a railing tool for things that aren't railings? Why isn't this documented somewhere?

Anyway just my 2c worth.

A Revit wiki was tried some time ago, but never took off.

For it to be remotely successful, Autodesk would have to host and maintain it, so that they are able to update it in advance so when a new version is released, the public are getting immediate benefits from it.

Just read the complete chapter and I think we're heading in the right direction in terms of information. Would still like to see more examples of difficult/unusual details and would still prefer some the these trickier details to be in flash or similar.

I also still believe we need further explanation on why you need to use one method over another and how that choice affects the outcome.

The graphics are poor. The Topic headings are only denoted by a slight change in the point size of the font. The Topic "Advanced Walls" left me scratching my head. After reading it I still could not figure out what was so "advanced" about retaining walls, or what were the important factors about using a retaining wall.
Throughout the chapter you use the term "add" when you mean "build". How to "add" a wall.etc. When you want to add a wall to your selection of wall types what term do you use?
The whole manual is very encyclopedic in nature and could make better use of graphics.

Sorry, but as usual this Autodesk info is totally saturated with jargon and overly technical explanations.

You need to start using a MUCH more graphical style, showing the points being made - not rambling and repeating yourself for pages then giving a barely useful image alongside.

Anyone that doesn't feel their eyes getting heavy and their brain going blank after a couple of minutes reading this kind of techno-ramble is impressive...

Hello. My name is Chris LaRoche and I am a User Researcher on the AEC User Experience Team.

Part of my job is to better understand user needs and make suggestions to improve the Revit user assistance/documentation over the next several releases.

Thank you for all your comments and suggestions about the Walls chapter and the conceptual aspect of our user assistance. Your suggestions were quite helpful and we are currently trying to analyze and sort through how we can incorporate your suggestions within the walls chapter and across the user assistance features. This will be a multi-year process. Please understand that we are making a concerted effort to better match your needs to the format and content of our user assistance. Thank you again and please contact me at if you have additional suggestions about how to improve our user assistance.

The comments to this entry are closed.


  • Subscribe