In this pair of posts, I describe the BricsCAD documentation system. Click here for part 1, where I describe the general Help system and the descriptions in the Settings command.

In this part, I discuss developer documentation and draw my conclusions.

Developer Help

If we count the Settings descriptions as a system, there’s a third documentation system for BricsCAD. The Developer Reference isn’t offline and included in an install like the main Help. Instead, it’s online, just like Autodesk’s default. Unlike Autodesk’s system, it works pretty well.

Being online means the performance suffers, of course, but it’s generally not too bad. It appears quicker than Autodesk’s. A link within the main Help system takes you to the Bricsys Developer Reference which is just accessed using your default browser. Of course, that means your mouse buttons work correctly and you have all other the advantages of whatever functionality is built into your browser.

Hot tip: you can get to a real browser from within the AutoCAD pseudo-browser thing too, by right-clicking on a link and picking Open in Browser. The URL takes a while to mangle and unmangle itself before you get to read any content, but you get there in the end.

Unlike the general Help, the BricsCAD developer Help system isn’t so obviously superior to its AutoCAD equivalent. This is largely thanks to the outstanding efforts of Autodesk’s Lee Ambrosius who has managed to take Autodesk’s pig’s ear of a system and produce perhaps not a silk purse but at least a decent-quality cloth bag. It can’t have been easy.

Like the main Help, the BricsCAD online developer reference has a Contents mode with structure:

There’s an Index:

And there’s Search:

As the last image shows, the system contains not only missing information (where’s the (entget) description?) but also broken links; this wasn’t the only 404 I came across. That’s a bit embarrassing, Bricsys. There’s a lot of work to be done yet to bring this up to scratch.

There’s no Favorites section, but of course that’s built into your browser so it would be pointless reproducing that.

Of course, you can’t get context-sensitive help on functions within your LISP code from VLIDE, because BricsCAD has no VLIDE.

Conclusion

The BricsCAD documentation system is notably better than the AutoCAD one in many ways. However, it’s a long way short of perfect. Many aspects need attention, and there are multiple holes to be filled. Sometimes I find myself forced to use AutoCAD’s general documentation system to find out something about a system variable that’s common to both systems. That shouldn’t be necessary.

I’ve hardly mentioned the content of the respective documentation systems, but I must say Autodesk’s content is often superior (thanks, Dieter). But there are exceptions; the BricsCAD descriptions and pictures of various commands and options are better in some cases. For example, try to find out what the various options of the PEdit command do in both systems. With BricsCAD, it’s all laid out on one page and nicely linked.

The AutoCAD command documentation has been pared down too much in places to make each page shorter and simpler, hiding the content beneath sometimes obscure links. It’s possible to find out what the Pedit options do in AutoCAD, but it’s certainly not BricsCAD-easy and I initially gave up after chasing my tail for a while. I went back and found it later, but it took a lucky guess. Giving up after looking through a circular set of links is a common experience with AutoCAD’s Help. There’s a programming concept called mutual recursion, but I don’t want to experience it during a vain search in a Help system, thanks. A visible, navigable structure would help eliminate that issue, but there isn’t one. There needs to be one. Did I mention that already?

With system variables, BricsCAD’s Help is consistently and clearly inferior to AutoCAD’s. The AutoCAD content also tends to be better worded, with the BricsCAD wording being occasionally slightly awkward in a non-native-English-speaking manner. There are also some formatting issues with wide gaps left where the system attempts to expand command descriptions to the right margin and does a poor job of it.

As with AutoCAD, there are many video tutorials available for BricsCAD. I have not considered these in my evaluation but the few I had a look at were pretty good.

Who wins? Nobody. It’s a draw. Both companies need to step up. Autodesk mainly with its awful structure-free system, Bricsys mainly with its incomplete content, particularly for developers. But both companies have work to do in all areas.

Because of the great similarity between BricsCAD and AutoCAD in terms of commands, variables and most aspects of usage, you would expect the BricsCAD documentation to be about the same too. But it isn’t. Much of the content covers the same areas and due to BricsCAD’s command-line compatibility, there must be a lot in common. But the Help system is very different from Autodesk’s. How so?

In this pair of posts, I describe the BricsCAD documentation system. I assume you’re familiar with the AutoCAD one. In this first part, I describe the general Help system and the descriptions in the Settings command. In part 2, I will discuss developer documentation and draw my conclusions.

General Help

The general Help system in BricsCAD looks a lot like the excellent CHM-based system that AutoCAD had in 2010 and earlier (thanks, Dieter). BricsCAD’s Help is offline by default, included with the standard download and installation, and very fast. Those are great things to have, and AutoCAD lacks them all. But the great thing about the BricsCAD Help system is that it supports different usage patterns, rather than Autodesk’s search-or-nothing method. Rather than telling users that they are expected to use Help in one specific way, Bricsys accommodates their disparate wishes. As usual, the customer-friendly way is the winner.

The BriscCAD system looks a lot more old-fashioned than the AutoCAD one. I don’t care about that. I do care about space-efficiency though, and BricsCAD is the winner there. You can of course resize the dialog and the size of the left pane.

There’s a Contents tab which allows you to navigate the hierarchical structure in which the information is arranged. That’s useful not only when looking for something in particular, but also when using the system as a self-teaching mechanism by working through an area and related topics. AutoCAD completely lacks such a structure.

There’s an Index tab that lists the indexed items in alphabetical order. You can start typing and the indexed items instantly change to reflect what you’ve typed, which is much more efficient than Autodesk’s system. AutoCAD 2018 Help does include an alphabetical list of commands and system variables in both online and offline versions, but it doesn’t give access to all of the topics.

There’s a Search tab that allows you to enter a search term and have several suggestions thrown up. Unlike Autodesk’s system, the suggestions are displayed in a space-efficient manner. Unfortunately, like Autodesk’s search, the suggestions displayed often differ from what you’re after. Even hitting F1 within a command doesn’t take you straight to the page for that command. In PEdit, the F1 visible suggestions don’t include the PEdit command page! It’s there, but needs a scroll down. That really needs work.

There’s also a Favorites tab where you can save and restore any pages you want to go back to.

But that hierarchical structure is the big winner. Destroying that structure in the AutoCAD 2011 pseudo-browser Help debacle and leaving it broken for seven further releases has to rank among the silliest self-destructive acts Autodesk has ever performed on AutoCAD. Because Bricsys never made that mistake, its general Help system is superior to AutoCAD’s. Until Autodesk throws away its flat-structure mindset and starts again, it has no hope of catching up to the BricsCAD system.

Oh, and your mouse’s forward and back buttons work in the BricsCAD system. How long have we been nagging Autodesk about that? Seriously, how hard could that be?

It’s not all good, though. As mentioned at the top, the AutoCAD content is generally superior. There are also quite a few holes. Enter a system variable at the command line and hit F1. You would expect to get context-sensitive information about that system variable. You don’t. You’re just taken rather uselessly to the “Welcome to BricsCAD” page. This needs attention to ensure context-sensitive help is available for all commands and system variables.

Fire up Help, pick the Index tab and start typing in a system variable name. In most cases, you’ll find it’s not in the list (e.g. FILEDIA). In cases where a system variable name does appear in the list (e.g. FILLMODE), double-clicking on it doesn’t take you to a description of the system variable. Instead, you will be presented with multiple topics and it’s often not clear which is the system variable description.

Settings Descriptions

For system variables and most other settings, you’re better off avoiding the main Help system altogether. Instead, use the Settings command. This is like Options in AutoCAD but superior, because it’s all there and arranged much more logically. You can navigate a hierarchical structure to find the setting you want, but you can also type part of the setting name or a related word into the search box at the top of the dialog. If that doesn’t take you immediately to the setting you’re after, you can use the up and down arrows to go to the next match. It’s all very quick and efficient.

Unlike AutoCAD’s Options, you don’t need to go hunting from tab to tab, visually scanning the dialog for the setting you want, which might be hidden under a button or not there at all. Also far superior to AutoCAD, the descriptions don’t hover over the dialog, obscuring what you’re looking at. Dieter has been hacking the AutoCAD dialog hover-tips down in size for years, but they still annoy the heck out of me until I turn them off.

When you find the setting you’re after, a brief description is displayed at the bottom of the dialog. In most cases, this has just the right amount of information you need without having to read through a whole page. If it doesn’t, in some cases it will tell you the setting name. However, this is missing in many cases.

This is a “could do better” area for Bricsys. Somebody needs to go through these descriptions, fill the holes (not a small job) and make them all consistent. While they are at it, get them to tie up all of the missing context-sensitive loose ends in the main system. Better still, provide a button or other method within Settings to take the user to the appropriate Help page. Currently, pressing F1 within the Settings command will give you useful but generic information about using the dialog. Unfortunately, it will not give you information about the setting you want to check or change. That needs to happen.

Click here for Part 2.