Development of documentation for CAD and BIM systems: peculiarities, tools for its creation and real examples
Dennis CraneWhat is CAD and BIM?
CAD (computer-aided design systems) and BIM (Building Information Modeling) are two types of software tools for creating and managing projects in the industrial manufacturing and construction industries.
BIM is a specialized subspecies of CAD that has more specific approach to design and uses a building information model. But it is not just a 3D model, but an intelligent database containing information about all aspects of the facility, including geometry, materials, engineering systems and more.
CAD is a broader term that encompasses a wide range of software tools used to create 2D and 3D models of various objects, including buildings, machines, and other structures. CAD focuses on the geometric representation of an object and allows the creation of visualizations and technical documentation.
Peculiarities of writing CAD user documentation
Without user documentation in CAD and BIM-systems it is extremely difficult to work even for an experienced specialist. Unlike simple graphic editors, where you work with two-dimensional images and deal with a limited set of tools, design software represents complex engineering structures and three-dimensional models containing huge amounts of data.
This makes the creation of user documentation for CAD and BIM systems an extremely time-consuming process. Authors have to not only describe the functionality of the tools, but also explain how different elements of the model interact with each other, what consequences may arise when making changes and how to avoid errors that may lead to incorrect results.
That's why user documentation for such software must take into account multiple scenarios of user actions and their possible consequences.
Writing user documentation for CAD and BIM systems is a task that requires a deep understanding of both the technology itself and the specifics of the user experience, which places special demands on the technical writer. When working on CAD documentation, the author should take into account several factors.
System Complexity
As we noted earlier, these systems integrate many tools that are difficult to understand for the untrained user. Therefore, the documentation should be structured in such a way that the required information can be found easily. A logical structure will help to find exact topic, the description of this or that functionality, and for this purpose the author should understand the program himself at a very good level. Ideally, a technical writer is a development participant, not a freelancer who sees the program for which he or she is writing user documentation for the first time.
Diversity of users
CAD and BIM users may have different levels of training and experience with such programs. Therefore, the documentation should be convenient for both beginners and experts. The author's task is to be able to explain the features to any user.
Technical terms
Like any industry, the construction field uses many specific terms and abbreviations. The writer will be required to have some basis for not getting lost in the names. When writing user documentation, it is important to explain complex concepts in simple and clear language, avoiding complex sentences, redundant terminology and abstract concepts. Clear, concise explanations are easier to remember and eliminate ambiguity and misunderstanding. Of course, it is not that easy to explain in simple, clear language how to install plug-ins, how to use virtual space, how to resolve conflicts between objects. Here we can use the proven method «from simple to complex».
Visibility
CAD and BIM are primarily related to the visual presentation of information, so the documentation should use a large number of illustrations, diagrams, screenshots and videos that will help the user to better understand the capabilities of the system. To visualize the functionality, you need a program for creating user documentation with the ability to capture the screen and tools to highlight the appropriate elements of the interface. This may take a lot of time, but it will have a positive effect on learning the material.
Relevance
CAD and BIM systems are constantly evolving, so user documentation must be updated regularly. It is important to keep track of new versions of the software and make changes accordingly. The technical writer should work closely with the system developers to get the most complete and up-to-date information. We wrote about how to keep the project up-to-date and avoid small mistakes that lead to serious problems in this post.
What should you consider when writing user manual?
They say that an intuitive interface does not need documentation. This is partly true, but, as mentioned above, people with different levels of technical literacy and specialists of different profiles can work with CAD and BIM programs. Without user documentation written in an accessible language, work on such a projects can lead to errors.
When writing user manual, you should consider that a program may have different ways of achieving the same result. For example, some tools help to speed up the model development process to the detriment of flexibility, while others increase the development time, but provide flexibility by allowing to enter the maximum number of numeric or text values in the object parameters. Drawing this information from the knowledge base, the specialist will choose the most appropriate toolkit to realize the business problem. As you can see, a technical writer must take into account many nuances.
Balancing text and media files
Creating effective user documentation for CAD and BIM systems requires a smart combination of text and visual elements. Images, videos and animations help provide an overall view of complex concepts, while text provides detailed descriptions and instructions. It is important to remember that visual elements should complement text, not replace it.
If the goal is a quick introduction to basic functions, visual elements can be emphasized. If a deep understanding of the principles of operation is required, more attention should be paid to the text.
Examples of wrong use of media content:
- too many images without textual explanations;
- too many animations that distract from the main content;
- low quality media files.
Flexibility
CAD and BIM tools evolve, some functionality becomes obsolete, and new functionality takes its place. Therefore, the documentation should be flexible and easily adaptable to changes. If at some point a certain topic loses relevance, its removal should not destroy the logic of the entire documentation.
Maintaining uniformity and consistency
Ensuring consistency in terminology and formatting across different topics of user documentation is important for clarity and ease of understanding. Creating clear and detailed diagrams, screenshots, and video tutorials in a consistent style will have a positive impact on the absorption of complex information.
Authors working on the same knowledge base should follow the same techniques and procedures. These include uniform terminology, designations, abbreviations, layout rules, a certain level of detail, rules for naming elements, fonts, lines, scales, symbols, etc.
For example, the Dr.Explain program offers not only structured templates for documentation design, but also a wide functionality for element styling.
It allows you to create annotated screenshots, customize export to the most common formats and organize collaborative work of a distributed group of authors.
Let's take a look at some examples of creating user documentation with Dr.Explain.
Real examples of creating custom CAD and BIM documentation with Dr.Explain
SolidPlant
Weerawat Charoenkoop, a lead software developer in the SolidPlant project, shares his successful experience of creating user documentation in Dr.Explain.
— SolidPlant offers a complete 3D software package which runs on top of SolidWorks. The add-in provides engineers, constructors, and owner-operators with comprehensive engineering software solutions. In order to make our application more user-friendly, we wanted to create a help system that guides the end user to work more efficiently in the software. Earlier we used to have a PDF training manual or document that the user needed to download separately from our website.
Weerawat Charoenkoop and his colleagues compared Dr.Explain with a few other applications, but they were not satisfied with the output result.
— Actually we were in search of a user-friendly application that would make it easier to create CHM to use offline or online. We found that Dr.Explain is quite user-friendly and supports multiple formats to export the project to. The output was quite perfect. We generated a CHM file to use within our application as a help document, and also to host it on our website. The function importing from a Word document is very useful. I like that function.
Turbomachinery Control Services Habets
Another successful integration experience is shared by Bertin Habets, the owner and head of TCSH bv.
— TCSH bv (Turbomachinery Control Services Habets) is a Dutch service company for gas and steam turbine control systems, predominantly for all GE Speedtronic systems (Mark IV, V, V-LM, VI, VIe, and Ve). During hectic situations, online manuals with a fast index and hyperlinks reduce machine downtime. When we used paper manuals, which were frequently misplaced, got coffee stains, and sometimes were lost.
Bertin uses Dr.Explain within his company today.
— Dr.Explain allows us to install the manuals on our Human Machine Interfaces (HMI is an operation and maintenance window for the control system), so that the manuals are never lost again. Dr.Explain makes it easy to customize the manuals to the customer site situation. It is a nice add-on to our products. On some of our HMIs, we pre-install Dr.Explain, so that the operators and maintenance personnel can update their manuals themselves.
Examples of user documentation for BIM and CAD systems
Let's also look at examples of user documentation for other design and modeling software. Perhaps you can find some interesting for your project.
Bentley OpenRail Designer
In the user documentation for Bentley OpenRail Designer, the authors decided to adapt the content for people with disabilities and added a button to call the accessibility menu:
Clicking on the button brings up the accessibility settings window, which is an entire widget:
Topics with a lot of text have anchor links that allow you to quickly navigate to the desired block, and there are forward and back arrows on the right side to navigate through your browsing history:
For some reason there is no «Up» button to quickly navigate to the top of the topic. Scrolling down the page every time is very tedious.
Vectorworks
In Vectorworks, a page dedicated to a particular tool starts with a compact table that gives an image of the corresponding button, describes its functionality and adds a keyboard shortcut. To the right is a button to add a topic to your «Favorites» list:
Navisworks
The Navisworks documentation uses annotated screenshots:
Bimcollab
The Bimcollab cloud service at the end of the page displays the number of positive and negative ratings of the topic, the time of the last update and a button to call a feedback form if the user wants to contact the authors:
Dr.Explain is a tool that speeds up the creation of user documentation for CAD and BIM systems
Sometimes you use Word text editor or Google Docs to write user help, but many things are impossible to realize in their limited functionality. For example, Dr.Explain, a program for writing user manuals, has the simplest and most intuitive interface and offers comprehensive functionality. Let's list some important features.
Collaboration
Dr.Explain offers the possibility of collaboration. If you have a distributed team working on your documentation, you can easily organize the collaboration of an entire team of authors.
Project templates
The program has templates with pre-prepared structure of topics and subtopics. This greatly speeds up the process of creating user documentation, which is especially important if you are writing such a project for the first time.
Stylized captions for numbered images and tables
Automatic numbering creates a logical sequence, maintains the integrity of documentation and facilitates navigation, while stylization helps to improve the perception of content and creates a unified visual image of the document.
Annotation Designer
This handy annotation designer is for editing screenshot annotations. It allows you to manage controls and numbered annotations.
Advanced export options
Dr.Explain allows you to export your project to the most common formats: HTML, DOC, PDF, CHM. While writing, you can check how the result will look like in each of these formats.
Imagine a situation when you are developing user documentation of an impressive volume and you would like to include in the final document only those topics that are relevant to the relevant subjects of construction activity: a financial expert will receive instructions without explaining the settings of variables for parameterization, and a version of documentation for an engineer will not contain information about contractors, deadlines and cost of works.
Such functionality in Dr.Explain is called topic conditional output. By setting different values of variables before exporting, you can control the composition of the resulting document. This approach is very convenient for creating several documents of different level of detail from one project. For example: User's Guide (minimal content) or Administrator's Guide (full content).
Conclusion
Writing user manual for CAD and BIM is a challenging but important task. A quality document is key to the successful implementation and use of the system and helps employees use it effectively to solve their tasks. The knowledge base creates a unified digital environment in which decisions are made quickly and projects are scaled up at minimal cost.
It can be said that the start of construction does not begin with laying the foundation, but with the choice of software for writing user documentation. It will form a competitive advantage, prevent your project from falling apart halfway through and become a good help in work for all project participants, while specialized tools will speed up and simplify the development of user documentation.