[Survey] The State of the documentationS and ways to improve it
- empireages
- Offline
- New Member
-
Less
More
- Posts: 4
- Thank you received: 2
21 Apr 2020 09:19 #164933
by empireages
Hi guys,
So I was reading the "Linux is Poorly Documented" thread and I think some valid points have been said by everyone involved.
Basically:
This thread is for referencing fact about the documentation so we can improve what is needed, IF needed. Please feel free to add on this list so we can have a non biased view of the documentation.
For example, for me, is it me or I can't seem to find a webpage where I can see What devs are working on ? Like a Objectif page or a status page ?
So here is my contribution to the subject :
before : image
after : image
For the after image, i used Sphinx as the html+pdf generator with ReadTheDocs theme.
What to you thinks, is it an improvement or not and on what?
So I was reading the "Linux is Poorly Documented" thread and I think some valid points have been said by everyone involved.
Basically:
- The main documentation come from github, then the linuxcnc.org forum, then the "outdated" WIKI.
- Some members would like a better way to see "Where" and know the "Categorie" in which they are currently in the doc.
- Users want a online HTML based docs BUT with the hability to have a PDF version for offline viewing and bundling with the app.
- The current documentation use ASCIIDOC file in .txt format that get converted to html + pdf at each commit.
This thread is for referencing fact about the documentation so we can improve what is needed, IF needed. Please feel free to add on this list so we can have a non biased view of the documentation.
For example, for me, is it me or I can't seem to find a webpage where I can see What devs are working on ? Like a Objectif page or a status page ?
So here is my contribution to the subject :
before : image
after : image
For the after image, i used Sphinx as the html+pdf generator with ReadTheDocs theme.
What to you thinks, is it an improvement or not and on what?
Please Log in or Create an account to join the conversation.
- tommylight
-
- Away
- Moderator
-
Less
More
- Posts: 17796
- Thank you received: 5918
21 Apr 2020 11:39 #164943
by tommylight
Replied by tommylight on topic [Survey] The State of the documentationS and ways to improve it
Personally, i like both as i do not care much how it looks as long as it has the info i need.
But i am pretty sure the second version is better for new users since they are used to everything on the web having colours.
Also, personally, it is not that Linuxcnc is poorly documented, but there is way to much info about everything in Linuxcnc, and that is a lot, that makes new users dizzy. On the other side, there are way to many types of machines, combination of equipment, different electronics, etc that are getting used with Linuxcnc, so that adds another level of complexity when trying to document everything.
Again, personally, i never had any issue with the documentation included with Linuxcnc, everything important is there, but frankly i rarely used them, so i might not be the best judge for it.
Linuxcnc user base is very wide, from absolute beginners in machine/software/electronics/etc, to highly experienced users in all of those subjects, so the main problem might be explaining thing to be easier understandable. Personally i was very bad at explaining things, i can understand almost everything just by a quick glimpse, and that took a lot of time to get there (over 40 years of experience with everything technology related), so this forum was a way for me to force myself to improve that, still work in progress.
There is also another issue related to this, and that is search. That was the main thing i learned long ago even before altavista was a search engine. If you search for example:
linuxcnc wiring stepper drive
you get a mess of everything on the net that include just some of those words, not all
but if you do :
linuxcnc wiring stepper drive site:linuxcnc.org
you get only results that include some of the words and only from Linuxcnc web site, forum and wiki, so you get what you need.
also
"wiring stepper drives" site:linuxcnc.org
will get you exactly that in results, only pages containing all of the phrases in that order.
That makes fore more targeted results, hence less frustration for new users and it will get them the answers they are looking for.
Fortunately, there are plenty of tutorials and howto's here and on the web, so a proper search would yield results quickly. But that again will not cover all the bases discussed above, due to the wast amount of equipment, but gathering some info here and some there should prove enough to get the job done.
All this is not saying that the docs are ok, most probably they can be polished a bit to cater new users with some examples, as that makes it easier to understand what is going on, so adding examples to the existing documentation would be a nice start. I.E. Linuxcnc has a lot of comps or components that get used a lot, so reading about them you get what each does and how it works, but most of the time there are no examples, so getting it to work poses a challenge for new users. Adding some examples to that would make it much easier to see what is going on and how thing interoperate.
Thank you for your effort, it is much appreciated.
But i am pretty sure the second version is better for new users since they are used to everything on the web having colours.
Also, personally, it is not that Linuxcnc is poorly documented, but there is way to much info about everything in Linuxcnc, and that is a lot, that makes new users dizzy. On the other side, there are way to many types of machines, combination of equipment, different electronics, etc that are getting used with Linuxcnc, so that adds another level of complexity when trying to document everything.
Again, personally, i never had any issue with the documentation included with Linuxcnc, everything important is there, but frankly i rarely used them, so i might not be the best judge for it.
Linuxcnc user base is very wide, from absolute beginners in machine/software/electronics/etc, to highly experienced users in all of those subjects, so the main problem might be explaining thing to be easier understandable. Personally i was very bad at explaining things, i can understand almost everything just by a quick glimpse, and that took a lot of time to get there (over 40 years of experience with everything technology related), so this forum was a way for me to force myself to improve that, still work in progress.
There is also another issue related to this, and that is search. That was the main thing i learned long ago even before altavista was a search engine. If you search for example:
linuxcnc wiring stepper drive
you get a mess of everything on the net that include just some of those words, not all
but if you do :
linuxcnc wiring stepper drive site:linuxcnc.org
you get only results that include some of the words and only from Linuxcnc web site, forum and wiki, so you get what you need.
also
"wiring stepper drives" site:linuxcnc.org
will get you exactly that in results, only pages containing all of the phrases in that order.
That makes fore more targeted results, hence less frustration for new users and it will get them the answers they are looking for.
Fortunately, there are plenty of tutorials and howto's here and on the web, so a proper search would yield results quickly. But that again will not cover all the bases discussed above, due to the wast amount of equipment, but gathering some info here and some there should prove enough to get the job done.
All this is not saying that the docs are ok, most probably they can be polished a bit to cater new users with some examples, as that makes it easier to understand what is going on, so adding examples to the existing documentation would be a nice start. I.E. Linuxcnc has a lot of comps or components that get used a lot, so reading about them you get what each does and how it works, but most of the time there are no examples, so getting it to work poses a challenge for new users. Adding some examples to that would make it much easier to see what is going on and how thing interoperate.
Thank you for your effort, it is much appreciated.
The following user(s) said Thank You: phillc54, empireages
Please Log in or Create an account to join the conversation.
- empireages
- Offline
- New Member
-
Less
More
- Posts: 4
- Thank you received: 2
21 Apr 2020 12:42 - 21 Apr 2020 12:47 #164955
by empireages
It's not that new user like me like colours everywhere but having consistancy across the docs, the wiki and the forum would be better because you learn how to navigate in one of the three and now you can use the two others without relearning for each how to find information. hope I was clear explaining that...
Basically in the docs, we need to have some "tutorial" from start to finish and we keep them updated :
-one tutorial for configuring a standard 3 axis mill
-one tutorial for a 2 axis lathe
- one for plasma cutter.
- etc
This will make a standard configuration that the new user KNOW it works flawlessly first try and that he can use as a base for HIS personal config.
I thinks it will be good if we can make a Main table of contents as a major guideline for user where everyone add name of categories and what subject you see in them so we can reorganise better the doc.
Like one main categories of the docs would be for new users, explaining linuxCNC ->e.g. About Linux
One for having a Operational LinuxCNC default interface -> Getting started
Another for the type of controller -> Integrating your Machine to LinuxCNC
A grand description of the architecture of LinuxCNC source code.
An documented API ?
etc
I thinks if we make one huge table of contents in this style, the documentation would be more useable for everyone because you would see what you want just by navigating in the categories based on your objectives.
Also, For each page, we should implement a tag that mark the page as valid for x.x version, like 2.7. then when 2.8 is published, the documentation automatically mark the page with tag != 2.8 as to be verified by user for validity. This will suppress the problem of having documentations everywhere that we don't know if it is still valid, useable or just to be trashed.
Also, we can make a page that guide the user to some common theme like
"you want hal component xxx ? You will find it with the other on yyy page" .
If making custom documentation example for each component was too cumbersome, we could make the documentation make the doc based on source file using the comments in the code itself.
What do you think of that ?
Replied by empireages on topic [Survey] The State of the documentationS and ways to improve it
But i am pretty sure the second version is better for new users since they are used to everything on the web having colours.
It's not that new user like me like colours everywhere but having consistancy across the docs, the wiki and the forum would be better because you learn how to navigate in one of the three and now you can use the two others without relearning for each how to find information. hope I was clear explaining that...
Also, personally, it is not that Linuxcnc is poorly documented, but there is way to much info about everything in Linuxcnc, and that is a lot, that makes new users dizzy. On the other side, there are way to many types of machines, combination of equipment, different electronics, etc that are getting used with Linuxcnc, so that adds another level of complexity when trying to document everything.
Basically in the docs, we need to have some "tutorial" from start to finish and we keep them updated :
-one tutorial for configuring a standard 3 axis mill
-one tutorial for a 2 axis lathe
- one for plasma cutter.
- etc
This will make a standard configuration that the new user KNOW it works flawlessly first try and that he can use as a base for HIS personal config.
I thinks it will be good if we can make a Main table of contents as a major guideline for user where everyone add name of categories and what subject you see in them so we can reorganise better the doc.
Like one main categories of the docs would be for new users, explaining linuxCNC ->e.g. About Linux
One for having a Operational LinuxCNC default interface -> Getting started
- sub categories for debian based
- sub categories for ubuntu based
- etc
Another for the type of controller -> Integrating your Machine to LinuxCNC
- sub categories for parallel port
- sub categories for mesa
- sub page for each Main Mesa config
- etc
A grand description of the architecture of LinuxCNC source code.
An documented API ?
etc
I thinks if we make one huge table of contents in this style, the documentation would be more useable for everyone because you would see what you want just by navigating in the categories based on your objectives.
Also, For each page, we should implement a tag that mark the page as valid for x.x version, like 2.7. then when 2.8 is published, the documentation automatically mark the page with tag != 2.8 as to be verified by user for validity. This will suppress the problem of having documentations everywhere that we don't know if it is still valid, useable or just to be trashed.
A revamped documentations system would also benefit use by having a better search system directly integrated like your example of google.That makes fore more targeted results
Also, we can make a page that guide the user to some common theme like
"you want hal component xxx ? You will find it with the other on yyy page" .
If making custom documentation example for each component was too cumbersome, we could make the documentation make the doc based on source file using the comments in the code itself.
What do you think of that ?
Last edit: 21 Apr 2020 12:47 by empireages.
The following user(s) said Thank You: tommylight
Please Log in or Create an account to join the conversation.
- tommylight
-
- Away
- Moderator
-
Less
More
- Posts: 17796
- Thank you received: 5918
21 Apr 2020 16:52 #164981
by tommylight
linuxcnc.org/docs/
And there are detailed tutorials, like
linuxcnc.org/docs/2.8/html/config/stepconf.html
That is for parallel port, there is also the Mesa section there.
That should be enough to get the machine working, but for more complicated stuff i agree that it would be nice to have some examples of editing hal and ini files, and some details of how things function inside hal.
Replied by tommylight on topic [Survey] The State of the documentationS and ways to improve it
Something like this ?Also, For each page, we should implement a tag that mark the page as valid for x.x version, like 2.7. then when 2.8 is published, the documentation automatically mark the page with tag != 2.8 as to be verified by user for validity. This will suppress the problem of having documentations everywhere that we don't know if it is still valid, useable or just to be trashed.
linuxcnc.org/docs/
And there are detailed tutorials, like
linuxcnc.org/docs/2.8/html/config/stepconf.html
That is for parallel port, there is also the Mesa section there.
That should be enough to get the machine working, but for more complicated stuff i agree that it would be nice to have some examples of editing hal and ini files, and some details of how things function inside hal.
Please Log in or Create an account to join the conversation.
Moderators: HansU
Time to create page: 0.110 seconds