LinuxCNC is Poorly Documented

More
28 Jun 2018 13:27 - 28 Jun 2018 13:31 #112983 by BrendaEM
In Looking at LinuxCNC, I find it sophisticated, powerful, and very adaptable.

Firstly, because LinuxCNC is sophisticated, it requires a greater amount of documentation, but the documentation is incomplete.

Just past the get-go, there is not a good-lay-of the-land overview of how LinuxCNC, as a system, works. Instead we are given close-sighted views of certain parts of if, without being given a brief overall view of what we are using, so we can place into context the information we may find.

it's like we are stumble upon a disconnected series of tools, but don't realize we are holding a Swiss army knife.

Yet, adding a brief overall view would fairly easy to fix, unless people haven't noticed or cannot admit that it needs fixing.

Secondly, there are not enough real-world examples in the documentation. If you look at the Arduino's documentation, or OpenProcessing, you will see an example of each statement in use. The would be an ongoing process to fix.

In a way, LinuxCNC is modest. It may admit it's almost an CNC operating system unto itself, but it's documentation doesn't admit that it's a CNC programming language as well.

Man(ual)-style documentation fails to work to explain the use LinuxCNC's .hal as a programming language.

Thirdly, the documentation needs to be written in a progressive disclosing way from the mundane to the esoteric to help the user, from venturing too deep in areas that don't apply. For example, the average user should know which twittles are commonly used, and which ones would be for fine tuning, going further.

Offering an entire law library to a defendant will only help them--after they have lost their case, and are spending the rest of their lives in prison, reading that documentation.


If you have gathered from that that I may be unwilling or lazy to read all of LinuxCNC's documentation, then I have made my point; the user should not need to read all of the documentation, they should be able to quickly learn what information is valuable and which is not.

Lastly, the documentation is presented in a fairly incoherent fashion. Traveling from system to system is a jarring experience for the user. The man pages look and work different as well. I've seen raw text, too.

linuxcnc.org/docs/html/
wiki.linuxcnc.org/cgi-bin/wiki.pl

There is an old saying that "Someone with one watch will always know time it is, but someone with two watches will never be sure."

If I'm right, then you have a situation, where:
  • LinuxCNC is being documented in the forums.
  • People have trouble understanding LinuxCNC configuration once they venture outside Stepconf.
  • The same few knowledgeable people help out on the forums, likely until they burn out, with a high turnover rate.
  • Information is being passed from person to person without context, meaning that people are learning what to do, instead of learning what they are doing .
  • To put it diplomatically LinuxCNC is not thriving as it should.

If you don't agree with me, then that's good. Hopefully, I have: made my point, given you examples, limited my scope of my complaining to the areas that most offend you, and presenting them in a manner where you could prepare your list of rebuttals. I wish no less for LinuxCNC's documentation.

(I might be able to help work some text out to spruce up the introduction, but I feel the most important thing I could document--is the state of the documentation.)
Last edit: 28 Jun 2018 13:31 by BrendaEM.

Please Log in or Create an account to join the conversation.

More
28 Jun 2018 17:04 #113000 by Sparky961
Excellent rant!

I couldn't agree more, but try to limit my own complaining because I don't have the desire to become seriously involved in the effort to fix things.
The following user(s) said Thank You: BrendaEM

Please Log in or Create an account to join the conversation.

More
28 Jun 2018 19:51 #113016 by Todd Zuercher
Funny, I've always thought the Linuxcnc documentation was reasonably good, and certainly much better than most open source software projects. Have you ever tried plowing through the documentation for a commercial CNC control? I have waded through a few, they were no less confusing or any more helpful.

Please Log in or Create an account to join the conversation.

More
28 Jun 2018 19:52 #113017 by andypugh
I am just wondering if you might have not found some of the docs.

I agree that the manpages for HAL components are not a great way to get an overview, but there are a couple of actually-in-words documents about HAL:

linuxcnc.org/docs/2.7/html/hal/intro.html
linuxcnc.org/docs/2.7/html/hal/basic-hal.html
linuxcnc.org/docs/2.7/html/hal/tutorial.html

Most times, when someone has a problem, I can find the section of the documentation that explains it. But that is because I have spent years searching the docs for answers and remember what is in there.

I agree that, at times, the documentation is incoherent, partly because different sections were written at different times in the history of the project.

The really unfortunate thing is that the Wiki is a morass of outdated and incorrect information. But that's user-generated content for you. I don't see a good solution.

Please Log in or Create an account to join the conversation.

More
28 Jun 2018 20:22 - 28 Jun 2018 20:38 #113026 by BrendaEM
Todd, yes, just recently I've been wading through the Huanyang VFD manual. It's terrible, and it's terrible because at times it fails to specify whether a voltage voltage are: line, PWM, or motor. And the first few frequency parameters are not agreed upon what they affect whether or not it's motor or line frequency. In many forum posts, I see people passing around erroneous information, a problem I have not seen witnessed surrounding LinuxCNC. Either people know how to work with .hal, or they are deathly overwhelmed by it.

I have read old Vexta manuals. The Yawasha Servo manual was interesting that only near the end of the manual, did I read that energizing their servo driver/amplifier too many times in an hour it would be ruined. When I read that, I scrapped out not only the driver I likely killed, but the remaining ones. I was not going to fuss with something so unreliable.
~

Andypugh, Andypugh, Andypugh, what an extremely helpful person you are for LinuxCNC, and myself. Thank you!
You make up for some of the Ozzyrobs of the world : )

On of my purposes in this thread was to make things a little easier for you, by cutting down on the same mundane stupid questions, asked over and over. Please don't stop me. LOL!

I've read those pages. I likely will want to contribute something to those pages, but right now, I have a lot of irons in the fire, and I am having problems with a forum member.

Which brings to mind....

Even though the thing I wanted to state was kind-of tough love thing about Linux-CNC, I appreciate how civil and respectful people have been. Thank you.
Last edit: 28 Jun 2018 20:38 by BrendaEM.

Please Log in or Create an account to join the conversation.

More
28 Jun 2018 20:46 #113028 by andypugh

BrendaEM wrote: Todd, yes, just recently I've been wading through the Huanyang VFD manual. It's terrible,.


Is it possible that you have a fake drive? My Huanyang manual is sort-of OK.

Is yours small but nicely bound?

photos.app.goo.gl/AaCXHEH5pNF1T7PG8

Please Log in or Create an account to join the conversation.

More
28 Jun 2018 21:00 - 28 Jun 2018 21:11 #113031 by BrendaEM
Yes, I got the perfect-bound (glued and wrapped) Deluxe Edition manual as well, though mine is not signed. LOL!
A lot of people have their AC service frequency entered in PD003.

My driver and motor appears to be genuine. You can tell it's a real Huanyang motor because the ground wire is not internally connected in the motor. Anyone making a forgery would accidentally connect the ground wire, you know, because it makes sense. The motor seems otherwise like a nice part. As a new Huanyang owner, I have big concerns about the Estop system in these drivers. Even on 110v single phase, the "2.2kw" motor runs like a bear. I hope to control mine from LinuxCNC, someday.
Last edit: 28 Jun 2018 21:11 by BrendaEM.

Please Log in or Create an account to join the conversation.

More
28 Jun 2018 21:41 #113033 by tommylight
I had no problems ever with linuxcnc, since the 8.04 version came out and i took it for a spin, oh what a joy that was.
I did try machX firts but i hated that ugly GUI like the plague and it was not easy or reasonable in any way form or shape, so after 20 minutes of messing with it i gave up and went on a hunt for something usable.
After 5 gruelling minutes of googling i was greeted by the Linuxcnc front page ( then named EMC2 ). It was love at first (web)site, it runs under Linux ( i utterly hate windows, but that is my opinion after being a victim of win3.1, win95, win98, catastrophic win98SE, skip win 2000 as it was a bit usable, and the terror of winXP, Vista gave me PTSD ! ), so i gently downloaded the iso, burned the CD at 180 degrees for 12 minutes and booted it, oh joy, start EMC2 and.........oooops to many things on the list but none of them mention "drives made out of scrap" or "machine from parts found at the junk yard" so back to menu to check it there is something else there and sure enough "stepconfig" was waiting patiently, took me all of 5 minutes to set it up and start that config, power the drives and press on the arrow keys... IT MOVES (never got it to move under mach as i was so mad at that GUI.....) , hmmmmm, home x,y,z, press run and the machine happily wrote the EMC2 logo.......upside down as i noticed later, i was staring at the screen falling in love with "AXIS". Alas another 3 minutes and all was good, moved on to dismantle said machine, build the next one, and the next and the next.......
It takes a lot of reading and actual use to get the hang of Linuxcnc, it takes much much more reading to be able to comprehend the possibilities it has and how versatile and powerful it is, it is extremely reliable for what it is, and very rewarding after some time spent with it.

My point is, you are right that the information is a bit on a heavy side, but i never look at it that way, i take it for what it is a use it as such: informations, plenty of it, so i read everything i can and make sense of it after i read it, not before. After a while it all becomes very clear and the world of possibilities is at your grasp.
All the time i am writing this i am thinking on how i could help with the problem you describe, but i am not good at explaining things as some other members of this forum. I wish i was, and all this post and other posts in this forum are my attempts at getting better at writing.
Thank you all.
The following user(s) said Thank You: BrendaEM

Please Log in or Create an account to join the conversation.

More
28 Jun 2018 22:09 - 28 Jun 2018 22:20 #113035 by BrendaEM
Tommylight, YOU! You were another person who helped me a lot. Thank you : )

Some years ago, LinuxCNC entered into the brainshare of the geekset. I downloaded a copy of the distro, just to try it out. It seemed pretty neat. I also checked out PyCAM, which I think also should be included with LinuxCNC's disk, which was out of development for a while, but is now again being developed, but not for Windows.

There is no reason, for me, personally to fault Mach3's appearance--when Mach4's license is the evil low-hanging fruit.

I've wanted a CNC milling machine for a scant thirteen years, but because I live on a fixed income, my plans to buy a small bench-top mill had been thwarted. I still own my beginner collection of R8 accessories.

A year and a half ago, a friend offered me some wafer fabrication machine parts. A little more than year ago, when another friend had stopped over, he asked me, "are you going to build something from those parts, or not?" So, I've been making a gantry milling machine mostly by hand. It's almost done. Though, now my housing situation is falling apart. Still, I want to finish it, which is crazy, but there I am. I've wanted to return something to the LinuxCNC community, so, I've been trying to do graphic project for it.

When I look at LinuxCNC, I see not only a lot of potential, but a lot of adaptability. If I where to find fault with it, I've found it here about the documentation and on LinuxCNC distro, I've found the omissions of NativeCam, the Probe Interface, and Pycam, baffling exclusions. People have done some great value-added stuff, and why should the creators of those additions have to deal with installation questions, when they could be creating more great software?
Last edit: 28 Jun 2018 22:20 by BrendaEM.

Please Log in or Create an account to join the conversation.

More
28 Jun 2018 23:01 #113037 by cmorley
I disagree with your title -poor documentation- but I do understand what you are getting at.

The learning curve is very steep - there are many disciplines and subjects you must become proficient in to build anything beyond a basic XYZ machine.

In fact just learning how to add/write docs is a fair learning process.

Documentation is not fun to write but there is a worse problem.
The person who makes the software is usually not the best person to do finish documentation.
They know how it is supposed to work and so don't get caught on all the first-time troubles.

There has been much work on the docs over the years and they are much better then when I first looked at linuxcnc. In fact i think it's one of the big positives of using linuxcnc.

My suggestion is to write some docs! As a relatively new person to linuxcnc you are able to see what might be missing or flow better or need more detail.
Even if you just write in simple plain text, there are people here that would be willing to incorporate the changes/additions if they will help others.
Start small - i find writing docs sucks the life force out of me - i would be very happy to write the general nuts and bolts stuff then have someone else go over it and make it more usable.
Big John would go through the pages and actually do the samples and rewrite the mistakes so they would work as described - That was great (under appreciated!) work!

Documents are a huge reason why a project does well or not I agree.
Machinekit IMHO is suffering from a lack of up to date docs of it's unique capabilities.
It's a major reason I didn't seriously try them out - which is too bad.

So please write a page of docs to help out.

Chris M

Please Log in or Create an account to join the conversation.

Time to create page: 0.129 seconds
Powered by Kunena Forum