Clarity?

Hi all,

LinuxCNC is not all things to all people but I would like to mention one thing.
Yesterday I spend all day to find out what LinixCNC is all about, a short introduction in about one paragraph.

In my search I stumbled on this text which is a *good* introduction, what I was looking for.
Then I found Rule of Clarity: Clarity is better than cleverness

To me the arrangement on 'linuxcnc.org/docs/2.8/html/' is not clear, misleading to a point!
The third set of documents (General User Information) should be the first set of documents

Yesterday I visited this page several times.
The first set of documents (Getting Started with LinuxCNC) is, to me, not about getting started but about getting LinuxCNC on your system.
The second set (Configuration WIzards) already asumes some understanding about the organisation of LinuxCNC, which, to me, is not yet explained.
Each set containd several documents and not finding what I was looking for I never opened documents from the third set (or anyone beyoud that point.

After googling for 'linuxCNC introduction' I found the second document from the third set. That was after a full day of trying to get a grip on it.

Please move the third set to the first position. The (current) first and second set do not make much sense without reading the third set first.

Kind regards.
 

I would agree that the first paragraph of the first document is a suitable high-level description of LCNC.

But I would also agree with the OP that after that the documentation isn't optimal for people trying to get a grasp on what it's all about.

My experience with technical documents intended for a wide audience is that they should move from the general to the specific as the reader progresses through them.  In this case, section 3 has some very useful overview topics which, if digested first, will help provide context for topics which are LCNC-specific.

A quick review of the first sections suggests to me the following order would be more clear to the uninitiated:

• General Overview
  • About LCNC
  • LCNC User Introduction
    • Needs updating to differentiate between architectures:
      • Parallel port arrangement
      • Mesa/Pico/Etc external stepgen boards
      • Ethercat or similar
  • CNC Machine Overview
  • Important User Concepts
  • User Forward
    • Rename to "LCNC Programming Philosophy" or "Why does LCNC seem insane?" or similar.
• Getting Started with LCNC
  • System Requirements
  • Linux FAQ
    • This is not a "FAQ" and should be renamed. This is an overview of Linux commands/features useful for new LCNC users.  Maybe "Linux Operating System commands & techniques"
  • Getting LCNC
  • Running LCNC
    • Combine with Starting LCNC
  • Updating LCNC
• Machine-Specific Overview
  • Lathe User Info
  • Plasma CNC Primer
• Configuration Wizards

Just some food for thought coming from someone who's had a pretty brutal last 9 months trying to learn LCNC.

-Ralph

The docs are good, if you take time to read them.

I'd always thought that the people that found their way over to Linuxcnc wanted a controller for their current or future cnc machine and were just looking around at the options.

The OP made me think of someone who may have been doing research on what cnc is, maybe for a degree or something along those lines.

The fact that they had to google for information that was more or less on the page they were looking at seems a little odd. Aren't people curious anymore ?

I think "misleading" maybe an exaggeration or mayhaps a language issue.

I actually read this post a few and didn't quite know how to take, so I kept my mouth shut.....I may have thought spam at first.