LinuxCNC is Poorly Documented

More
06 Jul 2018 10:52 #113555 by snoozer77
As a machinist, I usually find it hard to comprehend the manuals and docs. But honestly, I don't expect to be able to read a cnc control manual and understand it quickly. I have to YouTube, Google search, read examples etc, to slowly take it all in. I think it would be pretty difficult to cater for all levels of knowledge and experience.
Saying that, a beginners guide to linuxcnc would be great, but again, do you write it for people who don't know anything about cnc or controls? I think it is extremely difficult to write something quite technical, that caters for newby's like me but also gives the experienced people the answers they need in an efficient layout.
To be honest, I would love a manual that explains it all to I easy to understand language with examples and pictures and YouTube links, but really, no one is going to be able to achieve that.

Agree with rod about IRC. But also being in Aus, can't expect to see much action on there.

I do struggle with the search function on this forum. Am i doing something wrong to get a max of 20 search results.?? I can search "mpg Hal" and get a lot of my 20 results coming from the same thread. Think I'm going to start using tommy's Google trick from now on.

Just another new users 2 cents.

Have a good weekend all.

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

More
06 Jul 2018 11:14 #113559 by InMyDarkestHour
Under the keyword box there is a drop down list where you can search by the following options:

1: Search entire posts
2: Search Titles only

In your search example I seemed to get a better response by using "search titles only" and just using "mpg" rather tan "mpg hal"
The following user(s) said Thank You: snoozer77

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

More
06 Jul 2018 12:42 #113565 by snoozer77
Thanks Rob. i have been using the search titles, also been playing with the "search from" in the "date posted" option.
Just using your example, lve just searched mpg in "titles only" and got my 20 results. the date range for this search only spans 1 month.
another example, im using a mesa 7i49. do a search in titles only, get the same post 20 times (Are there no other posts with 7i49 in the title??), and if i search entire post instead of titles only, i get my own posts that i have mentioned the 7i49 in. I know i can play with the date settings, but it seems the results are limited.
Maybe im different, but i like to read a ton of posts on whatever topic im searching (7i49 for eg), but i struggle to do that on here.
Usually im not searching for anything in particular, just wanting to see projects, problems, examples, hal stuff etc.

cheers

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

More
06 Jul 2018 17:05 - 06 Jul 2018 17:13 #113589 by BrendaEM
Why conduct LinuxCNC business in an IRC chatroom, off of the forum, away from people, in a stateless protocol with no record of any kind?

Is there something that needs to be hidden from the community?
Last edit: 06 Jul 2018 17:13 by BrendaEM.

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

More
06 Jul 2018 17:45 - 06 Jul 2018 18:06 #113592 by BrendaEM
BTW, I have been looking for solutions for the documentation. I've looked at MediaWiki, which is the underlying base of Wikipedia, and a few others, such as the software that Git uses for their documentation, which is open--even of Git may not be for long.

As I have stated, part of the problem with the documentation is much of it is on dead-end web pages, quite long web pages that require a lot of searching and scrolling to find what you are looking for.

Part of the fix I am suggesting is to have a menu at the side, top or bottom of every webpage in the documentation, like this:
LinuxCNC/Configuring/Hal/Components/loadrt

In this way, as the user navigates the website, they learn what part of what the thing they are interest in is.

The documentation needs a search function.
The documentation needs a link to LinuxCNC home.
Each page needs a link back to documentation home.

I am not saying I have all the answers, but here is part of my suggestion to make it better, keep more new users, take some of the burden from the forum, and attract the developers who may not only keep LinuxCNC vital, but help include the feature you have always wanted.

There's also some exceptional information in the documentation. Like this page:
linuxcnc.org/docs/2.7/html/integrator/steppers.html

This page goes well beyond the call of duty. There's some great information here, but once again, there's nothing to remind the user where they are, or how to get back.

A frying pan needs a handle.

And once again, we don't need the numbers if no one reads the documentation as a book.

it would be great if we could a list the subjects on this page...
linuxcnc.org/docs/2.7/html/

...On the left, while we are reading this page.
linuxcnc.org/docs/2.7/html/integrator/steppers.html

If it's not what we are looking for, we can just click on the next or previous thing.
We don't have to reach for the [Backspace] key,

...and more importantly, we've never lost sight of where we are and where we can next go.
Last edit: 06 Jul 2018 18:06 by BrendaEM.

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

More
06 Jul 2018 18:25 #113595 by InMyDarkestHour

BrendaEM wrote: Why conduct LinuxCNC business in an IRC chatroom, off of the forum, away from people, in a stateless protocol with no record of any kind?

Is there something that needs to be hidden from the community?


It's a common method for many projects.

BrendaEM wrote: There's also some exceptional information in the documentation. Like this page:
linuxcnc.org/docs/2.7/html/integrator/steppers.html

This page goes well beyond the call of duty. There's some great information here, but once again, there's nothing to remind the user where they are, or how to get back.


The address bar will tell you where you are, the back button is a great way to get back to where one was previously (you gotta hand hand it to the browser guys, they are smart like that). Or if you want you can always open a link in a new tab.

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

More
06 Jul 2018 18:57 - 06 Jul 2018 18:57 #113598 by BrendaEM
AnnoyingMutt, expecting that the user to use the addressbar for webpage navigation is just bad web design.
Last edit: 06 Jul 2018 18:57 by BrendaEM.

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

More
06 Jul 2018 19:44 #113599 by BigJohnT

BrendaEM wrote: Why conduct LinuxCNC business in an IRC chatroom, off of the forum, away from people, in a stateless protocol with no record of any kind?

Is there something that needs to be hidden from the community?


You sure do have a narrow view on things! If you bother to read the EMC history you would know that the IRC and the mailing list came way before the forum. In an attempt to reach people who think forums is the only thing on the internet the forum was added. And none of those communication protocols are for Documentation. The ONLY documents are the PDF and HTML documents. The wiki is a user contributed area like the forum where users try and help other users often by just giving a link to the "Documents"..

JT

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

More
06 Jul 2018 19:48 - 06 Jul 2018 19:55 #113600 by BigJohnT

BrendaEM wrote: Part of the fix I am suggesting is to have a menu at the side, top or bottom of every webpage in the documentation, like this:
LinuxCNC/Configuring/Hal/Components/loadrt

In this way, as the user navigates the website, they learn what part of what the thing they are interest in is.

The documentation needs a search function.
The documentation needs a link to LinuxCNC home.
Each page needs a link back to documentation home.


That's a good idea, you should take that task on. Actually a link to the documentation home would be enough because there is a link on the documentation home page for the LinuxCNC home page.

I do see a huge problem with the auto generated HTML pages they would have to know what the base URL is for the docs... it will be interesting for sure to figure that out.

Keep in mind that it is unlikely that the base document structure and generation process will change unless you show that a completely new systems is both open source and uses the same GPL that we use.

JT
Last edit: 06 Jul 2018 19:55 by BigJohnT.

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

More
06 Jul 2018 20:33 #113604 by BrendaEM
What is producing the index, currently?

I agree that whatever solution is used, it must be open source. Additionally, I would never want to suggest leading the documentation anywhere to create more problems further down the road.

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

Time to create page: 0.124 seconds
Powered by Kunena Forum