LinuxCNC is Poorly Documented

More
03 Jul 2018 04:45 - 03 Jul 2018 04:56 #113292 by BrendaEM
I spent some more time looking at the documentation. I have a few theories:
1.) I think that the effort to maintain both a .pdf version of the documentation and a HTML version has been an undue burden.
2.) I suspect that the writers of the documentation were either overwhelmed by keeping multiple versions and/or version changes.

I agree that the forums here, and more importantly, the individuals who help out the forums are invaluable. It would be helpful if a greater amount of that tried-and-true information becomes documentation and FAQs.

As an experiment, if you see a thread where people are helping people, pick some at random, and look at the number of "Thank You"s that person has received.

Aside from the content: I feel it would be greatly beneficial to have always have enough menu in view to give context to the information presented. On the top of this webpage, we see that we are in:
General > Documents > LinuxCNC > LinuxCNC is Poorly Documented > Reply

A few ideas to toss around:

Beginner to expert level information:
www.python.org/doc/

Multiple examples:
docs.julialang.org/en/release-0.4/manual/strings/

A grouped reference or a lot of information:
processing.org/reference/

A bad documentation webpage example, with pretty colors:
www.arduino.cc/reference/en/#functions
I don't know what happened to Arduino's website : O

Anyway...

A great second-tier goal would be to make it easier to Program LinuxCNC, yes, I feel that's I think about it.
Last edit: 03 Jul 2018 04:56 by BrendaEM.

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

More
03 Jul 2018 04:57 #113293 by InMyDarkestHour

cmorley wrote: linuxcnc used to use Ubuntu to lower the barrier to new adopters.
it was a perfect solution. Their ideology worked well with ours.
Then Ubuntu went all nutto and wanted to commercialize and worry about their image etc.
Most importantly they said that you must remove all branding if you respin the DVD.
Debian is dedicated to free software and doesn't make such demands.
But it kinda sucks for beginners.

Untill we get permission to use or figure out how to unbrand -
I think we are stuck.

Chris M


I've just started working on it for Mint 18.1 as that is what I'm currently running......I imagine working through the branding may take a while.....at least I'll get a little closer to getting something done and if it fails ? Meh a bit of time and electrons spent.

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

More
03 Jul 2018 05:06 #113294 by InMyDarkestHour
If you sue the iso you even need to install anything to get a feel for Linuxcnc by using one of the simulations.

The whole Debian packaging system is based on not having to manually install dependencies for .deb packages.

Using the iso negates the need for having to install anything to get a basic system going...it's all there. Granted an updated iso would be a good idea.

What needs changing to get people started milling & turning ? One has to consider that there is a million ways one can put a cnc mill\router\lathe\plasma cutter together.

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

More
03 Jul 2018 05:44 #113296 by curtisa

ozzyrob wrote: What needs changing to get people started milling & turning ? One has to consider that there is a million ways one can put a cnc mill\router\lathe\plasma cutter together.


I'm thinking about those of us who got started with one of the thousands of pre-assembled ready-to-go CNC3020, 3040, 6040 6090 etc units available on eBay or Aliexpress or Banggood for a pittance.

Ok, how about:
  • For the total beginner - updated list/offerings of officially supported ISO installs, can LCNC be offered as an Appimage like Freecad ?
  • For the more adventurous beginner - a couple of formally-written tutorials on how to install from source on Mint 18 or Stretch or Ubuntu 16.04 or...ie, take what is currently on the Forum and if it is validated as being 100% correct, formally publish it
  • For all users - neaten up some of the formal documentation, particularly the basic stuff; if the Wiki is such a mess then perhaps push it away from the frontpage of the website with a view to eventually nuking it; put some more examples/showcases/user galleries up on the front page (big yourselves up!); dare I say it, give the website a bit of a spit and polish - TBH it's pretty vanilla-looking

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

More
03 Jul 2018 10:24 #113304 by rodw
Replied by rodw on topic LinuxCNC is Poorly Documented

cmorley wrote:
Until we get permission to use or figure out how to unbrand -
I think we are stuck.

Chris M


It just occurred to me that we may be looking at this problem the wrong way round.

What if we approached the Mint guys and offer to maintain a PREEMPT_RT .iso that includes LinuxCNC? That makes much more sense. Maybe you might need to get the audio guys onside (the other real time aficionados) for a bit more momentum. There is not that many releases of the Real Time kernel each year so maintenance should not be too onerous.

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

More
03 Jul 2018 12:13 #113313 by InMyDarkestHour
That's the kind of thing I was thinking of...Approach the Mint guys, maybe explain the situation and see what happens.

To install linuxcnc on stretch, uspace & Preempt anyways, is only about 15 or so lines of very very simple commands. Mainly just apt-get.

When I got my 7i92 from JT it came with an instruction sheet on how do it.

RTAI maybe another kettle of fish.

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

More
03 Jul 2018 12:47 #113315 by BigJohnT

BrendaEM wrote: I spent some more time looking at the documentation. I have a few theories:
1.) I think that the effort to maintain both a .pdf version of the documentation and a HTML version has been an undue burden.
2.) I suspect that the writers of the documentation were either overwhelmed by keeping multiple versions and/or version changes.


Your theories are wrong.

The generation of the PDF and the HTML is totally automatic and they are generated from the same text file.

Versions of LinuxCNC are no problem, a commit that is applicable to 2.7 and Master will get pushed up hill from 2.7.

I welcome your submissions to the Documents.

JT
The following user(s) said Thank You: InMyDarkestHour

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

More
03 Jul 2018 16:00 #113330 by tommylight
Close ............but no cigar!!!
More actual useful stuff, less discussion, please.
Most of what is here is not helping the cause you keep discussing. Write a few nice lines about Linuxcnc, some tips, helpful whatever, edit the wiki, do some nice graphic for it, launch a nuke...... hmmmm... never mind.
The following user(s) said Thank You: InMyDarkestHour

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

More
03 Jul 2018 16:13 - 03 Jul 2018 16:16 #113332 by BrendaEM
Though I am still green, I likely will write some documentation, though elsewhere I am trying to design a new user interface for LinuxCNC, but to be blunt, why should I write something if I am not going to be able to find it after submitting it?

I feel that context is often very important to the understanding of information.

Is there a way that menus could be added to the documentation, so the reader will always know where they are?

Could some of the HAL components be on their own pages, and still have menus that remind the user of where they are, like in other programming language webpages?

That way the user would know where they are, and they won't have to either search or scroll to find the information they want.

This is a brief description of (likely) all the HAL components, with no examples or syntax, or expected parameters:
linuxcnc.org/docs/2.7/html/hal/components.html

Here is a description of eight of them:
linuxcnc.org/docs/2.7/html/hal/rtcomps.html

There some here:
linuxcnc.org/docs/2.7/html/hal/basic-hal.html

There is HAL two-pass, and post-gui information broken out here, for some reason, on the same page.
linuxcnc.org/docs/2.7/html/hal/twopass.html

[Also, the two pass thing is a unique feature of LinuxCNC, so people aren't going to implicitly know what it is, as a heading, are they?]

By the time the user gets into the man pages, not only do they have no context to the information they have been given, they have no way back other than the browser back button. I strongly feel that there are better ways to teach people LinuxCNC than dissociated man pages.

There is likely valuable documentation in the wiki, that should be verified and integrated into the documentation.

If few people read the pdf's, the heading numbers likely needlessly slow people when tirelessly scanning long documents.

Which is more useful?
Chapter 1.5.2.a
Linuxcnc/Hal/Components/
Last edit: 03 Jul 2018 16:16 by BrendaEM.

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

More
04 Jul 2018 00:17 #113352 by InMyDarkestHour

tommylight wrote: Close ............but no cigar!!!
More actual useful stuff, less discussion, please.
Most of what is here is not helping the cause you keep discussing. Write a few nice lines about Linuxcnc, some tips, helpful whatever, edit the wiki, do some nice graphic for it, launch a nuke...... hmmmm... never mind.


Can we have a link (with menu & context) to the launch a nuke hal component ?

Now the boyish silliness is out of my system, I'll endeavor to continue on a more serious note.

Whilst linuxcnc is a great collection of OSS with many individuals working on it, it is not perfect in everyone's opinion. If you feel it is lacking in some area, feel free to identify that area and not only propose a fix but try to implement a working fix for review. Don't get upset with an disagreement as people with have differing ideas as to what works and what does not. Ask as to why they disagree, it maybe enlightening. Both sides may emerge enlightened.
If you make a change, such as installing a new desktop for greater real estate, share the way you did it with others. And bookmark it for future reference.
And finally try not to make suggestions for changes sound like demands and appear inflexible.
The following user(s) said Thank You: tommylight

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

Time to create page: 0.127 seconds
Powered by Kunena Forum