LinuxCNC is Poorly Documented

More
05 Jul 2018 20:41 - 05 Jul 2018 20:42 #113516 by BigJohnT

BrendaEM wrote: BigJohnT,

I feel bad that no one even took the time to comment on the links I took the time to post in this thread.
I have also been researching alternative documentation solutions.

This forum, looks and works great. It is well-organized. People can find information. The manner in which information is presented is consistent and understandable. If the documentation was this, I would have never taken the time to engage in this thread--especially since I've been having a problem with a member here--who continues to drag my topics into the ground.

I am sorry to go off-topic, but this is the nature of how I am stepping up to the plate:
forum.linuxcnc.org/41-guis/34572-a-wides...nder-style-interface

It's not done yet, but I've been working more than 20 hours a week on trying to design an interface that has the best aspects of Axis, Gmoccappy, a touch of Touchy, Razzy, and even a bit of Craftsman--all in the style of Blender. There are still a few more menus to go, but it's getting there. If you go through the thread, you can see how it has evolved. Someone is already working on implementing the design before it's even done : )

I am sorry if my opinion and my message about the documentation is not a positive one, and I cannot help but notice the effect the state of the documentation has.

I guess I could have chosen a more diplomatic title for this thread, and yet, that is my opinion to express, and express in hopes that it might lead someone to improve the documentation. Yes, I likely will write something, but as I have stated, I am pretty new at .hal. I am having a tough time learning it from the documentation.

In my opinion, the documentation system/method needs a serious overhaul. I am sorry, but once land on a dead-end webpage with no menu to tell you where you are or how to get back, there is a problem.


I don't understand why the documentation (not the wiki or google searches) needs a overhaul. There are no bad links as far as the w3clinkchecker can find. Most people when they find a dead link anywhere in LinuxCNC land will give the page they found it on so it can be fixed or deleted as the case may be, not say the whole documentation system needs an overhaul.

Your GUI is a lot of work, although I don't care for that type of GUI when it gets to be part of LinuxCNC please ask for my help in documenting it in the official documents. I have been working on the documents for a long long long long time trying to present things that a newbee can understand because I started out knowing one thing, I wanted a CNC machine. When I first started I would find typos and stuff that needed fixing. Once I became part of the then EMC2 team of volunteers and had push rights I started removing duplicate information from the "User Manual" and the "Integrator Manual" with the final move to put everything into one document so links within the document could link to anything which was not possible with the split up documents.

My suggestion instead of declaring the documents to be crap to instead use what ever means you want to communicate any errors in the documents to me.

Often I don't have time to visit the forum due to work demands and other time sinks even though I pushed it through to start the forum. The best place to find me is the IRC.

JT
Last edit: 05 Jul 2018 20:42 by BigJohnT.
The following user(s) said Thank You: Mike_Eitel, InMyDarkestHour

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

More
05 Jul 2018 21:11 - 05 Jul 2018 21:15 #113517 by curtisa

BigJohnT wrote: I don't understand why the documentation (not the wiki or google searches) needs a overhaul. There are no bad links as far as the w3clinkchecker can find. Most people when they find a dead link anywhere in LinuxCNC land will give the page they found it on so it can be fixed or deleted as the case may be, not say the whole documentation system needs an overhaul.


I think what BrendaEM and myself feel (and maybe others, I dunno?) is not that the technical aspect of the documentation is broken, but it could be presented in a more casual, easy to read way. I personally find the Stepconf documentation section to be pretty good. The PncConf section in comparison doesn't quite have the same level of accessibility and fluidity (some of the screenshots and text even make reference to it being beta and liable to bugs - is this still the case?).

I was actually going to ask if IRC was even still a thing that people used for seeking technical support in preference to the forum, but I see you're offering your services via it. That said, on the About LinuxCNC page, the very first one I looked at when BrendaEM raised the issue of documentation quality, the link provided to start the embedded java IRC client gives me a 404. I haven't looked at other pages to see if there are other broken links, but my immediate thought was it wasn't the best start on the first page I clicked on to see what the fuss was about.
Last edit: 05 Jul 2018 21:15 by curtisa.

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

More
05 Jul 2018 21:19 - 05 Jul 2018 21:22 #113518 by BrendaEM
Sir, "Your GUI is a lot of work" is likely true. I only mentioned it because you suggested that I wasn't making contributions, in response to something you said.

The Debian version of Mint is Debian, is likely very similar in the Debian LinuxCNC uses.

I doubt that Mate is as popular as Cinnamon. It's listed first...
www.linuxmint.com/download.php

And here are some Cinnamon reviews.
www.linuxandubuntu.com/home/cinnamon-des...t-for-new-linux-user
opensource.com/article/17/1/cinnamon-desktop-environment
www.zdnet.com/article/hands-on-with-linu...3-cinnamon-and-mate/

I am sorry if I bruised your ego, but I think the documentation needs a lot of work, more organization, and a uniform web design, with menus all along the way.

Who else is working on the documentation?
Who is helping you?
Last edit: 05 Jul 2018 21:22 by BrendaEM.

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

More
05 Jul 2018 21:21 #113519 by BigJohnT

curtisa wrote:

BigJohnT wrote: I don't understand why the documentation (not the wiki or google searches) needs a overhaul. There are no bad links as far as the w3clinkchecker can find. Most people when they find a dead link anywhere in LinuxCNC land will give the page they found it on so it can be fixed or deleted as the case may be, not say the whole documentation system needs an overhaul.


I think what BrendaEM and myself feel (and maybe others, I dunno?) is not that the technical aspect of the documentation is broken, but it could be presented in a more casual, easy to read way. I personally find the Stepconf documentation section to be pretty good. The PncConf section in comparison doesn't quite have the same level of accessibility and fluidity (some of the screenshots and text even make reference to it being beta and liable to bugs - is this still the case?).

I was actually going to ask if IRC was even still a thing that people used for seeking technical support in preference to the forum, but I see you're offering your services via it. That said, on the About LinuxCNC page, the very first one I looked at when BrendaEM raised the issue of documentation quality, the link provided to start the embedded java IRC client gives me a 404. I haven't looked at other pages to see if there are other broken links, but my immediate thought was it wasn't the best start on the first page I clicked on to see what the fuss was about.


Thanks, I'll fix that link when I return from my short short short vacation. Unfortunately the w3clinkchecker does not check external links we rely on reports like yours.

Yes the IRC is very active and the Community link on the home page will lead you to the IRC.

Again if you have any specific corrections to the documents please let me know. General suggestions are hard to put into words...

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

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

More
05 Jul 2018 21:50 #113520 by curtisa
Tell you what. Time permitting, I'll have a crack over the next few days at re-wording the LinuxCNC User Introduction page. I feel that's a good example of a page that doen't meet the same level of quality as other documentation sections. I'll upload a PDF of my version here when I'm done.
The following user(s) said Thank You: tommylight

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

More
05 Jul 2018 21:56 #113522 by BigJohnT
Just make a .txt file of the changes and contact me via the IRC or email me.

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

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

More
06 Jul 2018 07:30 #113539 by rodw
Replied by rodw on topic LinuxCNC is Poorly Documented
I have to say I've tried the IRC and found when you live on the other side of the world 10-15 hours ahead of most users, its not a workable communication channel for me. When you guys are on, I'm sound asleep!

I think the core implementation stuff is OK, and I think many forum users are a bit lazy asking questions without attempting to find a solution.

My biggest beef has been inability to drill down to component documentation but that has been covered in this thread earlier. If nothing else, this thread taught me how to find what I was looking for. However, sometimes, the component is documented far too tersely and I'm none the wiser even if I find it.
The following user(s) said Thank You: InMyDarkestHour

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

More
06 Jul 2018 08:27 #113545 by tommylight
www.google.com

In the search box type as is:
search term for whatever you are searching site:linuxcnc.org

this will search only inside the linuxcnc.org domain

search whatever site:linuxcnc.org filetype:pdf

same thing but will only show pdf files

etc
It is called "google hacking" and google will display everything as there are a lot of this type of search filters.
This is just in case anybody needs it.
The following user(s) said Thank You: akb1212, snoozer77

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

More
06 Jul 2018 08:40 #113547 by InMyDarkestHour

rodw wrote: I have to say I've tried the IRC and found when you live on the other side of the world 10-15 hours ahead of most users, its not a workable communication channel for me. When you guys are on, I'm sound asleep!

I think the core implementation stuff is OK, and I think many forum users are a bit lazy asking questions without attempting to find a solution.

My biggest beef has been inability to drill down to component documentation but that has been covered in this thread earlier. If nothing else, this thread taught me how to find what I was looking for. However, sometimes, the component is documented far too tersely and I'm none the wiser even if I find it.


Oh yeah I agree with the lazy part...more so when the question being asked has been covered more than once in a thread. :angry:
The following user(s) said Thank You: rodw

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

More
06 Jul 2018 09:45 #113551 by cmorley

curtisa wrote:

BigJohnT wrote: I don't understand why the documentation (not the wiki or google searches) needs a overhaul. There are no bad links as far as the w3clinkchecker can find. Most people when they find a dead link anywhere in LinuxCNC land will give the page they found it on so it can be fixed or deleted as the case may be, not say the whole documentation system needs an overhaul.


I think what BrendaEM and myself feel (and maybe others, I dunno?) is not that the technical aspect of the documentation is broken, but it could be presented in a more casual, easy to read way. I personally find the Stepconf documentation section to be pretty good. The PncConf section in comparison doesn't quite have the same level of accessibility and fluidity (some of the screenshots and text even make reference to it being beta and liable to bugs - is this still the case?).

I was actually going to ask if IRC was even still a thing that people used for seeking technical support in preference to the forum, but I see you're offering your services via it. That said, on the About LinuxCNC page, the very first one I looked at when BrendaEM raised the issue of documentation quality, the link provided to start the embedded java IRC client gives me a 404. I haven't looked at other pages to see if there are other broken links, but my immediate thought was it wasn't the best start on the first page I clicked on to see what the fuss was about.


Now that is tangible criticism. Giving a concrete example is much more helpful.
Pncconf will always be beta and buggy unfortunately. But the docs could be improved.
Can you be a bit more specific? is it the wording? The layout? the tone? The actual information? not enough pics? too many?

Chris M

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

Time to create page: 0.128 seconds
Powered by Kunena Forum