Documentation for LibreCAD Developers

Hi guys,

I've got a couple of items that should probably at least get a mention on the LibreCAD GitHub wiki.

1.  I have completely reorganized the LibreCAD-2 GitHub Labels in order to make them more useful for filtering, searching, creating the release notes, etc.  However they cannot reach their maximum potential unless developers, you know, actually use them.  I have provided a summary of my changes and a system specification here: (#1106)

2.  I have fixed the Visual Studio build problems, which reduces the number of steps needed to basically 3.  GaryS feels this is still to complicated to be mentioned in the users's manual.  I don't agree (developers are users too Gary), but these new instructions should be documented at least somewhere.  They could replace the old Visual Studio instructions on the wiki, as those ones will no longer work with the move to Qt5.

I don't yet have access to the wiki to make the changes myself.

Thanks,
Shawn.

On second thought, it looks like I do in fact have access now.

Disregard.

I've added a page for GitHub Labels:  wiki

If there is any documentation meant to be read by people who would like to contribute to the project, please include a link to the above wiki page and a recommendation to use them on all Issue tickets.

I also updated the Visual Studio build instructions in the Compile HOWTO.  I deleted the old instructions since they don't work.  It now appears that the only thing remaining on that page, which is not already in the User's Manual, are these (very simple) instructions.  Since none of the other documentation seems to ever link to this page, the only reason it appears to exist now is to bury these instructions where nobody will find them.

By the way, the supplemental instructions linked to by the User's Manual don't work either (dead links, old info, etc).  It's not helpful to include these.

The documentation (user guide and command references) are being reworked and updated at https://librecad.readthedocs.io/en/latest/appx/build.html and bulding procedures are  part of this update.
This is the reason why we asked for compiling feed-back on the forum. Feel free to amend the building procedure and feed-back on Zulip.

Fabrice,

The new page layout looks great!  I'll work on a write-up and submit it as a pull request.

Thanks,
Shawn.

Shawn.Curry wrote

...

2.  I have fixed the Visual Studio build problems, which reduces the number of steps needed to basically 3.  GaryS feels this is still to complicated to be mentioned in the users's manual.  I don't agree (developers are users too Gary), but these new instructions should be documented at least somewhere.  They could replace the old Visual Studio instructions on the wiki, as those ones will no longer work with the move to Qt5.

...

I agree the instructions should be documented somewhere, however I strongly disagree that the User Manual is the right place for them.  The User Manual is an end user document, the VS build instructions are for developers.  Those are two separate audiences and each one has separate documentation repositories - the User Manual on RtD and the developers' documentation on the GitHub Wiki.  I also stated that the intent was to keep the number of steps to a minimum.  Although I'm not a fan of the term, the KISS principle applies here.  It is the number of required steps that addes complexity.

To suggest that there are 3 steps is being disingenuous.  The steps you provided are:

   - Follow all of the instructions for building LibreCAD 2.0 on Windows. The steps for "Building LibreCAD in Qt-Creator" may be omitted.
   - Install the appropriate Qt Visual Studio Tools plugin for your version of Visual Studio.
   - RTFM. Set it up.
   - Qt VS Tools > Open Qt Project File > librecad.pro
   - Build

In terms of adding the VS instructions to the Build guide I wrote, there are a few things:
1. I count five steps in your instructions, but yes, the last two are insignificant.
2. The first step involves multiple steps and since it deals with the heavy lifting needed to get the build environment setup, the last couple of steps to build in the Qt environment for an end user are insignificant.
3. You gloss over the need to download and install VS (several hundred MB of VS in addition to the several hundred MB that  are required for Qt and the libraries).
4. They lack the required detail for the User Manual (again, it is a different audience and end users require a lot more detail; "RTFM. Set it up" isn't going to cut it).

Further to the above, there is a separate effort to update the current LibreCAD wiki and that effort separates the two types of documentation (see the discussion in Zulip Chat).  Adding the developer documentation to the User guide is a step in the wrong direction.

Shawn.Curry wrote

By the way, the supplemental instructions linked to by the User's Manual don't work either (dead links, old info, etc).  It's not helpful to include these.

Are you referring to the new User Manual on RtD?  The links in the User Manual on RtD point to GitHub.  Can you cite the link?

Feedback was requested to ensure the build process works as described.  At this point they do for both Linux (Debian) and Windows.  I still don't know about macOS...

Gary S wrote

I agree the instructions should be documented somewhere, however I strongly disagree that the User Manual is the right place for them.  The User Manual is an end user document, the VS build instructions are for developers.  

I strongly disagree with your strong disagreement.  

Developers are users too Gary, and they're just the sort of users who are going to be looking for the "Build from source" instructions.  This is doubly true of the audience interested in doing so on Windows.  And even if they're not planning to do any development, you're asking them to have:

Gary S wrote

-C++ compiler and related utilities
-Qt development framework
-Boost C++ source library

These folks aren't going to wilt when they see a few additional steps for Visual Studio.  Indeed, that's probably the C++ compiler they already have.  It's Qt that will be unfamiliar to them.  

My point is, why make them hunt down the instructions someplace else?  I had to figure it out on my own, I never found the other instructions.  They sure would have been nice to have.  

The part that burned me up, was that the first time I interacted with you, you were looking for a review of the windows process, which wasn't working.  Well here I am Gary, a professional windows developer for the past 15 years, who just guided 2 more of his coworkers through the process as well.  But you don't want to listen to any of my recommendations; it seems like you're more interested in engaging in a "turf" war with me or something.

In regards to your critiques of my "write-up" (if you can even call it that), you were absolutely right.  It's like you point out in the manual,

GaryS wrote

Developers are usually bad in making documentation,

Indeed.  That's why we have 2 tech writers in the office now.  You would have been horrified to read our old help documentation.  I absolutely welcome any critique you would offer.  Likewise, I also have some more recommendations for the windows process, if you're willing to listen to them.

-Shawn.

No, I'm not interested in turf wars - I’m interested providing a clear, concise User Manual.  I'm started with a particular intent and I am wary scope creep - so yes I'm going to push back, even if it takes a good debate on the merits of one or the other..

No, developers, or anyone else, should not have to hunt down the desired information – whatever it might be.  In the new User Manual there are numerous links from the Build from Source section and from the How to Contribute section that provide far greater detail for developers building the application on a variety of OSes that can be put in the User Manual; cover the minimum in the manual and provide all the gory details in the Developers’ wiki.  and I have no doubt that they, developers, won't wilt at the thought of installing a library or another tool, but the opposite cannot be said for a user who doesn't have developer skills - I don't want to overwhelm them and scare them away.

"Developers are usually bad in making documentation"  can't be attributed that to me...

Fair enough, I suppose we can "agree to disagree" on the Visual Studio point (c'mon man, it's the appendix!) as long as it's linked to from the main area.  Will you accept any of my other critiques of the windows process?  I feel like this really hasn't been tested from scratch lately.  Now that everything is working again you should try uninstalling everything and starting over.

1.  The Qt offline installer path should not be recommended.  They no longer offer this method from the main page; these installers can now only be found deep in their archive.  My coworker, Doug, who follows instructions with superhuman precision, tracked these down and got into a real mess because of it.  

They don't include the "kits" (libraries + compiler) that you need.  These need to be located, downloaded, installed, and configured separately with much effort if you take this path.  Your steps don't mention this part.  The online installer allows you to not only install the program but also select the latest versions every available kit you might want.  Plus, this path makes it possible to use the windows "Add/Remove Programs" dialog to reconfigure your kits later on.  Otherwise you can't.  Had to figure this all out the hard way.

If you're building with Qt, choose from the MinGW kits (32 or 64bit).  If you want to build with Visual Studio, choose from the MSVC kits.  Or both if you like.

2.  If you want to save some space, there's really no reason to mention muParser.  Its simply an included library, there's no way you could do anything different with the way the project is set up.  I mean you could, but the process would certainly be more involved than the Visual Studio build.  

3.  Tell ya what.  Include my VS steps, and I'll pay for it by eliminating the file copying steps.  I can make a batch file to run the windeployqt.exe tool, which is the proper way to deploy the files anyway (it scans all current dependencies, you'll get the translation languages, etc).  Then you can just tell folks to run that.  

Sure.

1.  I had originally referenced the online installer as it is front and centre on the Qt site.  The LC wiki instructions I pulled this from explicitly recommended the offline installer, and yes, I did have to dig for it.  And, it's a big download since everything is included.  I've used both and the online installer worked almost identical to the offline installer, even using the windows "Add/Remove Programs" dialog to reconfigure.  I'm a little suprised to Doug had to locate additional downloads. I didn't mention it as I didn't need to find any further downloads - one or two checkmarks on the Select Components page was all that was required.  That may be a problem with having to dig for a download of the offline installer on the Qt site.  I'm happy to change it back to the open-source online version as it is shown on the main dowload page.

MinGW is shown as a required component:
   "On the Select Components page include the latest version of the compiler, MinGW, under the most recent version of Qt, e.g. MinGW 7.3.0 32-bit and Qt 5.12.3 respectively."

Is there something else missing for building in Qt?

2.  It is a FYI.  It is mentioned as a dependency common to all they OSeses.  Those  that are more observant might wonder if it is not mentioned, but I doubt it.

3.  I added a note with a link in the appendix specifically mentioning building on VS 2013 and later to the  Build from source instructions.

A single command line script to do the whole thing would be easier.  The LC wiki build instructions does offer a script to build a package , but required a bunch of editing.

Thanks for chasing this topic.

Shawn, do you think this build proceedure could be Windows release dependent ? If so, could you please mention the release in the build instruction ? Just to make sure that failing build under another release has more chances to be reported to the team.

Gary S wrote

...The User Manual is an end user document, the VS build instructions are for developers.

Until very recently, any Mac user had to build if he wanted a version that wasn't four years old. I found the build instructions completely inadequate for my geek level. I'd be happy to help critique the documentation from the "dumb user" point of view.

Depending on how deep you want to involve, I suggest :
- Register to Zulip chat to get in touch with developpers and documentation maintainer.
- Register to github to access to the code and documentation data including code, wiki, issue management system, etc. This requires more knowledge (including git tool) but it is the place where the work is done and managed.