BricsCAD documentation – a tale of three systems – part 2

BricsCAD documentation – a tale of three systems – part 2

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.

3 Comments

  1. Thanks for this objective look at these help systems Steve. I like being able to press F1 and get contextual help sometimes, but I also like being able to lay a physical book down beside the keyboard and look at real ink on real paper, made from trees!

    I know those days are gone, so whatever we can do to make this electronic help better, I’m all for.

  2. Torsten Moses

    Dear Steve,

    all that LISP related documentation is also included in the “LISP Developer Support Package” (“LDSP”, free download at the Bricsys Application Catalog) – and contains 3 help systems (CHM, PDF, HTML).

    That online documentation part (where you have shown the broken link) is a kind of reproduction of that LDSP package, so likely the broken link(s) were introduced by that merge.

    But of course, the LDSP works proper.

    side note : the standard AutoLISP functions like (entget) are not documented, as there are plenty docs on the web for this;
    but we document any extension beyond AutoLISP standard, even for the standard functions.

    many greetings !

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.