BricsCAD documentation – a tale of three systems – part 3

BricsCAD documentation – a tale of three systems – part 3

In this third post in what was supposed to be a two-part series, I have more to say about the BricsCAD documentation system. See here for part 1 and here for part 2.

Developer Help – Addendum

In this comment from Bricsys API person Torsten Moses, he informed me about the availability of the Lisp Developer Support Package (LDSP) in the Bricsys Application Catalog. As always, when presented with new evidence I am prepared to re-examine my position on anything. Therefore, I will now further discuss the BricsCAD developer documentation.

The first thing to mention is that the existence of the LDSP package is not obvious. To somebody who uses BricsCAD as-provided and as goes burrowing down through the Help system looking for information, that system is still broken. The documentation as presented to the user remains sub-standard, exactly as described in part 2.

Assuming you know of the existence of LDSP, how do you go about using it? Here are the steps:

  • Go to the Bricsys Application Catalog site, click in the search field and start typing LDSP (you don’t need to hit Enter).
  • The link to the Lisp Developer Support Package (LDSP) will appear: click that.
  • Enter your email address, accept the privacy agreement and pick Download. (Note in passing that this is actually published by Torsten’s own company, not Bricsys).

  • If you’re already a registered Bricsys user (you will be if you’re evaluating it), the download will start. If not, you’ll be expected to register (free):

  • Once you’re registered, the download results in a 12 MB file called Lisp Developer Support Package.rar (RAR is a ZIP-like format).

Any recent commercial ZIP utility (e.g. WinZip) will open RAR files and there are a variety of freeware/adware/shareware utilities available to do likewise. For example, RAR Opener in the Windows Store will present itself as the first option in Windows 10. But it goes without saying that going off in a hunt for utilities wouldn’t be on anyone’s expected to-do list when just looking for product help. A bunch of people would give up here, if not earlier.

I went through with installing RAR Opener, but when I attempted to open the LDSP file I saw this:

Oh, and a handful of empty folders were produced. Is there an email waiting for me at work with the password (my Bricsys registration email is at work but I’m at home)? Am I really supposed to have a password to open this RAR? If so, why wasn’t I prompted for one? RAR Opener doesn’t present me with that option anywhere I can see. Is the download corrupt? Does it refuse to work on a Sunday? I have no idea.

At this stage, many more would give up. How many prospective customers would be filtered out by this experience? There’s no way of knowing. However, I’m made of sterner stuff and persevered with downloading and installing another app from the Windows Store. 9 zip did the job and uncompressed the file, no password required.

Yes, the RAR Opener problem I had above isn’t a Bricsys problem directly. But it is indirectly, because the file I was given to deal with won’t open by default in Windows, where the vast majority of BricsCAD users will be working. It’s a level of obfuscation that you can get away with when dealing with cellar-dwelling geeks handling obscure pieces of open source software. It’s not appropriate for customer-facing documentation in a mainstream CAD application. Yes, even developer documentation, because with CAD applications like AutoCAD and BricsCAD, most of the developers are customers/users/managers, not people trying to sell utilities.

Once you manage to get the file uncompressed (it becomes 41 MB), there are three help systems provided in there (CHM, PDF, HTML). That’s excellent, and conforms nicely with the Bricsys philosophy of providing customers with choice. I was unable to find any broken links. However, even in the LDSP, standard AutoLISP functions are undocumented. So I still couldn’t find the (entget) help I was looking for in part 2:

According to Torsten:

…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.

Sorry, but while “we don’t have that information but you can Google it” might have been an acceptable answer for a cheap AutoCAD clone’s API documentation ten years ago, that’s not where BricsCAD is today and most definitely where Bricsys wants it to be in future. Just two days ago, Bricsys CEO Erik De Keyser sat across a table from me and told me that BricsCAD isn’t intended as merely an AutoCAD alternative, but must go well beyond that in order to prosper. He’s right. The BricsCAD developer documentation today is not compatible with that vision. I know it’s that way for historical reasons, but we’re now at a different point in the historical timeline.

Conclusion – Addendum

My conclusion from Part 2 remains valid, despite the existence of LDSP. Both Autodesk and Bricsys have work to do. Downloading LDSP will help with some of the BricsCAD developer documentation failings but leaves plenty behind. It also provides its own set of unfortunate challenges.

This isn’t just a technical and ease-of-use failing, it’s a marketing one. That’s because it acts as a stumbling block to conversion of AutoCAD sites to BricsCAD. Disaffected AutoCAD power users in small sites and CAD Managers from large sites are right now taking tentative steps to evaluate the suitability of BricsCAD to replace AutoCAD in their complex LISP-heavy custom environments. They’ll want to know what’s the same and what’s different so they can estimate the effort and cost involved in the transition before getting in too deep. I know this, because I’ve done it myself. The first thing they will come across in their search is disjointed, very inconvenient and incomplete. It presents a less-than-professional image.

Some potential customers, like me, will persevere and discover that the quality of the developer tools implementation far exceeds the expectation generated by the documentation. Others will give up well before they reach that stage, and that’s a shame.

11 Comments

  1. Steve,

    Agree totally with your conclusions. That said, the do a lot with so few resources, and Torsten is a thoroughly helpful guy. How many times can you say that you’ve had direct contact from the person that implemented the code when you’ve struck an issue?

    The help portion of the LDSP (terrible acronym) is now at least included in the developer help.
    https://www.bricsys.com/bricscad/help/en_US/CurVer/DevRef/index.html
    Although at times they can be out of step with each other.

    I’ve always used 7zip, and had no issues with unpacking rar files. To access the contained help may require you to Unblock the file from windows explorer. Obviously this could be avoided if they used a signed installer.

    BricsCAD Lisp users may also like to know that you can get Doslib, and OpenDCL for BricsCAD. Both can be found in the applications area.
    https://www.bricsys.com/applications

  2. The much bigger issue than any zip format or help documentation is that once you open the LDSP, you discover two things: 1) you cannot compile a project to “separate namespace” mode which means any global vars are exposed as if the project was not compiled. 2) there is no lisp debugger. While newer people tend to think lisp is old school, its actually not because a good cad manager knows you need to troubleshoot startup (acaddoc.lsp) issues in situ, not back at your cad manager desk. The fact that bcad has ever so slight differences in its lisp handling makes this important as “it works on acad, so what’s the problem” hits you and you have to start inserting (princ “step x”) things to tell you how far it got. Without a debugger, you have to be pretty good at lisp to fix stuff and that is the number one thing preventing bcad from being acad IMO.

      1. Dieter Schlaepfer

        I haven’t done much brain-bashing since my college days. I do have to admit that some of the areas you’re visiting are nearly as beautiful as the rural Swiss countryside of my native country or the northern Napa valley in California (Valley of the Moon) near where I now live. Yes, Trappist beers are indeed very nice (I don’t want to start a war).

        To keep this from becoming totally off topic, let me contribute the following. Solid support from an accurate, succinct, well-written, and well-organized Help system is very difficult to achieve . . . and to maintain! When an architect or engineer is under deadline pressure and something in their software seems to be blocking them, they typically try a bunch of stuff and only reluctantly access the Help system. Once there, if an answer isn’t immediately available, it’s so easy to go ballistic. I admit that I do on occasion with the software I use.

        The best conceptual topics in AutoCAD are organized to answer the following questions in this order:

        – What is this?
        – Why should I care?
        – How is this supposed to work?
        – Where are there caveats, limitations, or exceptions?

        Each of these questions needs to be answered clearly by someone who is intimately familiar with using the feature. You can’t write about something you’re clueless about, and you need to communicate what you know effectively with words and illustrations. Frankly, I’m never completely satisfied.

        Dieter

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.