New users try out Machinekit -- You won't believe what happens next!

[sliptonic]

Sorry for the long read that follows (and the click-bait subject). I think all of this is part of a single issue of user-friendliness that needs to be addressed together.

It's a Sunday afternoon and I'm sitting here trying to catch up on things in the Machinekit world and I'm facing the same frustration I faced six months ago.  And a year ago.  And a year and half...

I'm left with the distinct impression that Machinekit is not a user friendly project.  To be sure, the project is full of very friendly people but the project itself has a systemic problem that doesn't seem to be improving with time.  This was completely understandable when the project was new and just getting its legs but we're now more than two years on and things don't seem to be improving.

I think that this is a pressing problem because it means we aren't bringing new users to the project.  More importantly, we aren't creating that class of 'power users' that, in other open-source projects, provides support, writes end-user documentation, and files bug reports.

While Machinekit has an uncompromising focus on writing excellent software, there's almost no effort at making the project more approachable, or flattening the learning curve.  I'll cite a handful of specific example to make my point:

Main website

The website should do three things; 1) tell people what Machinekit is.  2) Help them understand the current state, organization, and direction. 3) Point them to more effective resources depending on their needs.  The current website does a poor job at all three.

- Go to the project page machinekit.io.  Click the 'blog' link.  It looks like you've entirely left the site! There's No consistent look or navigation.  Try to go back to the main page.  You have to use the browser back button because there's no link at all.  If you come in from an external link, you have to hand-edit the url to get to the main page.

- The top navigation is completely arbitrary.  Why are there links to github but not to packages? The two top/left links (and 3 of the 5 menu items) are of no use to an end user at all.

- The blog is the most interesting part.  It is rarely updated.  As of this writing, the first three posts are hardware related and the most recent status post is November of last year.  A monthly or quarterly report of status would be a vast improvement.

- The About page says nothing about the history or origin of the project.  If a user hears that MK is a fork of linuxcnc, they have no idea why the fork was needed, what the goals of the new project are, or what the relative merits of the project are.

Official Documentation

I know documentation has been getting some focus lately but right now it's a mess.

- I did a  google search for 'machinekit documentation'.  #1 result doesn't go to the github docs but to the project documentation page.  From there, the most useful link is the 6th one down (after the blog and the issue tracker) and buried in text.  As an end-user, I know I'm expected to 'RTFM' but I can't tell which 'FM' the project expects me to 'R'.

- The #2 Google result goes to readthedocs.  Once there, The first link tells me to 'always read the README file first'.  Unfortunately, the README link is 404. I'm not joking.  The first link in the official documentation is broken.

- Using github as a system-of-record is really smart from a development point of view but it raises the friction for end-user contribution. If we're not going to use a wiki for documentation, then we have to have a tool-set that is at least as easy to use. The alternative is that documentation is maintained almost exclusively by the developer community.

- Overall, the documentation quality is pretty bad.  Even some of the machinekit specific stuff is out of date or broken.  Documentation is heavily weighted to traditional 'man page' style and very light on real-world examples that a user could copy and learn from.

Bottom line: I think the overall friction to contribute is really high and the results reflect this. if we're going to stick with git, we're going to have to lower that friction. A lot.

Google Group

By far, the most useful resource for MK is the google group.  Almost any issue a new user is likely to face has already been addressed.  But it's flat.  There's no categorization or structure so a user has to just start reading or searching.  Searching depends on knowing the right keywords so success is variable.

Just reading the group is very informative but the discussion is overwhelmingly developer centric.  A new user will be intimidated and reluctant to even ask a question.

If user frustration is high enough and they ask a question, they generally get help but that burden is landing squarely on developers shoulders.  Just in the last couple days I saw a new user startup thread that went to 25+ replies.  It was all pretty basic stuff about setting up a BBB but was almost entirely Bas and Charles answering.  (Did I mention the project is full of nice people :-)

An anecdote:  A couple months ago, I recommended MK to a friend who was doing a mill conversion.  I talked to him a couple weeks later and was surprised to hear he went with LinuxCNC.  When I asked why, he expressed frustration with the resources.  Since his conversion was pretty basic, He went looking for specific examples to copy. Unable to find anything, he decided he didn't have time to wade through years of Google group posts to try to figure it out.  This guy is a professor of electrical engineering at the University.

Bottom line: The google group feels useful but in a lazy way.  It puts all the burden on the end user. No sticky topics, no tag clouds, nothing that helps a user navigate the fire-hose of information.  It's all or nothing.  Content isn't separated by demographic (Users vs developers) or interest area (GUIs, HAL, etc), architecture (PC, BBB, RaspPi), application (robots, drones, mills, etc) or anything else.

Github Issues.

I was really interested to follow the Machinekit + ROS initiative and somehow I got subscribed to the github issue.  Very cool stuff!  Then the discussion just disappeared because the issue was closed.  There was no summary, blog post, documentation, or roadmap.  If the work continues, I'm unaware.

I don't think the issue tracker itself needs to change, but somehow the end-user implications need to make their way to end-user outlets.

Because I was interested in the MK+ROS thing, I went hunting. Issue #689 got almost 200 comments often averaging 5-10 per day.  Once closed, issue

#898 should have taken its place.  So far, it hasn't received a single comment.  By closing the issue, we lost all the momentum but we also lost all the community that had formed around the issue.  If someone had commented on the original, they were auto-subscribed and got updates but that disappeared when the issue was closed.

Bottom line:  Tons of useful information gets buried in the discussion and never sees the light of day. Issues don't work for long-term initiatives because either the community is destroyed when the issue is closed, or the issue grows without structure forever. For all the good info buried in the issue discussions, an end user wouldn't even know to search there.

Other Community.

I'm sure there are people doing interesting things with MK and maybe blogging about it but I can't find them. The Machinekit project is doing a spectacular job with the software, but the human side is getting neglected. Although there was (is) a lot of things wrong with the LinuxCNC project, I miss how easy it was to ask questions, learn from each other, and make friends.

Am I alone in my frustration?

-sliptonic

-- 

Brad Collette
573-427-7132

[Bas de Bruijn]

Hi Brad,

> On 25 Apr 2016, at 18:04, sliptonic <shopint...@gmail.com> wrote:
>
> Am I alone in my frustration?

No you're not.

I don't have better response now. Speaking for myself: I share your frustration.

Bas

[thematsche]

It's a pretty good brief summary. :)

On 2016-04-25 18:04, sliptonic wrote:
> Sorry for the long read that follows (and the click-bait subject). I think
> all of this is part of a single issue of user-friendliness that needs to be
> addressed together.
>
> It's a Sunday afternoon and I'm sitting here trying to catch up on things
> in the Machinekit world and I'm facing the same frustration I faced six
> months ago. And a year ago. And a year and half...
>
> I'm left with the distinct impression that Machinekit is not a user
> friendly project. To be sure, the project is full of very friendly people
> but the project itself has a systemic problem that doesn't seem to be
> improving with time. This was completely understandable when the project
> was new and just getting its legs but we're now more than two years on and
> things don't seem to be improving.
>
> I think that this is a pressing problem because it means we aren't bringing
> new users to the project. More importantly, we aren't creating that class
> of 'power users' that, in other open-source projects, provides support,
> writes end-user documentation, and files bug reports.
>
> While Machinekit has an uncompromising focus on writing excellent software,
> there's almost no effort at making the project more approachable, or
> flattening the learning curve. I'll cite a handful of specific example to
> make my point:
>

> *Main website*

> The website should do three things; 1) tell people what Machinekit is. 2)
> Help them understand the current state, organization, and direction. 3)
> Point them to more effective resources depending on their needs. The
> current website does a poor job at all three.
>
> - Go to the project page machinekit.io. Click the 'blog' link. It looks
> like you've entirely left the site! There's No consistent look or
> navigation. Try to go back to the main page. You have to use the browser
> back button because there's no link at all. If you come in from an
> external link, you have to hand-edit the url to get to the main page.
>
> - The top navigation is completely arbitrary. Why are there links to
> github but not to packages? The two top/left links (and 3 of the 5 menu
> items) are of no use to an end user at all.
>
> - The blog is the most interesting part. It is rarely updated. As of this
> writing, the first three posts are hardware related and the most recent
> status post is November of last year. A monthly or quarterly report of
> status would be a vast improvement.
>
> - The About page says nothing about the history or origin of the project.
> If a user hears that MK is a fork of linuxcnc, they have no idea why the
> fork was needed, what the goals of the new project are, or what the
> relative merits of the project are.
>
>

> *Official Documentation*

> I know documentation has been getting some focus lately but right now it's
> a mess.
>
> - I did a google search for 'machinekit documentation'. #1 result doesn't
> go to the github docs but to the project documentation page. From there,
> the most useful link is the 6th one down (after the blog and the issue
> tracker) and buried in text. As an end-user, I know I'm expected to 'RTFM'
> but I can't tell which 'FM' the project expects me to 'R'.
>
> - The #2 Google result goes to readthedocs. Once there, The first link
> tells me to 'always read the README file first'. Unfortunately, the README
> link is 404. I'm not joking. The first link in the official documentation
> is broken.
>
> - Using github as a system-of-record is really smart from a development
> point of view but it raises the friction for end-user contribution. If
> we're not going to use a wiki for documentation, then we have to have a
> tool-set that is at least as easy to use. The alternative is that
> documentation is maintained almost exclusively by the developer community.
>
> - Overall, the documentation quality is pretty bad. Even some of the
> machinekit specific stuff is out of date or broken. Documentation is
> heavily weighted to traditional 'man page' style and very light on
> real-world examples that a user could copy and learn from.
>
> Bottom line: I think the overall friction to contribute is really high and
> the results reflect this. if we're going to stick with git, we're going to
> have to lower that friction. A lot.
>

> *Google Group*

> *Github Issues.*

> I was really interested to follow the Machinekit + ROS initiative and
> somehow I got subscribed to the github issue. Very cool stuff! Then the
> discussion just disappeared because the issue was closed. There was no
> summary, blog post, documentation, or roadmap. If the work continues, I'm
> unaware.
> I don't think the issue tracker itself needs to change, but somehow the
> end-user implications need to make their way to end-user outlets.
>
> Because I was interested in the MK+ROS thing, I went hunting. Issue #689
> got almost 200 comments often averaging 5-10 per day. Once closed, issue
> #898 should have taken its place. So far, it hasn't received a single
> comment. By closing the issue, we lost all the momentum but we also lost
> all the community that had formed around the issue. If someone had
> commented on the original, they were auto-subscribed and got updates but
> that disappeared when the issue was closed.
>
> Bottom line: Tons of useful information gets buried in the discussion and
> never sees the light of day. Issues don't work for long-term initiatives
> because either the community is destroyed when the issue is closed, or the
> issue grows without structure forever. For all the good info buried in the
> issue discussions, an end user wouldn't even know to search there.
>

> *Other Community.*

[Alexander Rössler]

It's especially sad because it's actually pretty easy to get Machinekit
up and running if you just know how.

At the moment I have no time to take this task, but I think it would be
great if we could form a small "task force" including devs, writers and noobs
to update at least the getting started documentation.

The real problem starts when we differ between CNC and Non-CNC use. I
think the LinuxCNC project did a pretty good task documenting the CNC
stuff. However, there is a huge number of people out there searching for
exactly what HAL does but have no interest in CNC stuff at all. I think
we should make clear on the website that Machinekit can do
both.

Regarding GitHub and Docs: Its actually pretty easy to edit them, since
GitHub provides online edit functionality. Same for the website. Maybe
there should be a small tutorial for that? Seriously, there is no need
to install git for editing the docs, Github does all the git magic for
you.

--
Alexander

[Norbert Schechner]

At the moment I have no time to take this task, but I think it would be
great if we could form a small "task force" including devs, writers and noobs
to update at least the getting started documentation.

That is what I was asking with issue "kernel install documentation is wrong", I got a way to use a work around, I created an issue and have been asked to change that doku, but my knowledge is not enough to decide, what is the correct way to go.

I share the frustration and I am not sure any more, if I should develop "gmoccapy based on haltalk and Qt" or just make a QtPhythonVCP for linuxcnc.
I like the people here and also the possibility to take influence on the future of this project, but....

There is no good software without good documentation!
I am willing to contribute, but please only on the part I have knowledge on.
Doku on writing a GUI, a python handler, or even the python part of haltalk etc. could be my part.

I do like the idea of the task force!

And I will do my next install try, after the kernel part has been documented.

Norbert 

[Tom M]

I have to say, I'm have great time trying to figure it out  project out and for me the treasure hunt is a good learning experience for me. 
I can see a bbb and a cramps board with cheap polulo's being a fantastic way for someone to get started with cnc.

In my research,  it seems like I was having I was constantly being taking back to the linuxcnc site for documentation. ( My deadline is under two weeks away... yikes)

I guess, the question I have as a long time and somewhat distant watcher is, how forked are these projects?   From what I understand is that machinekit is trying to push the envelope  beyond a cnc machine tool controller.   On strictly cnc portions of machinekit derived from Linuxcnc,  would it be a dump idea to have a machinekit sub-section on the linuxcnc site?   I think that could potentially benefit both projects and it would allow machinekit to focus on project documentation  that go beyond cnc.  

Is that something that could happen getting people together with a few kegs of beer and a visit to a sweat lodge or has the fork progressed so far that this is no longer realistic?
Tom

[Kenneth Lerman]

My understanding of why the fork occurred is:

1 -- LinuxCNC has a goal to just work. It must continue to work, it must be easy (and get easier) to install, use, update, etc.

2 -- Machinekit would like to replace all of the ancient cruft that exists because it has always been there with new, modern, flexible, clean, understandable technology. It isn't important if that causes temporary dislocations where transitions are difficult. If the documentation doesn't keep track with the release, that's OK.

You won't be able to reintegrate the fork until such time as machinekit is "done" -- whatever that means. I think that must include getting rid of nml (or replacing it), building a new interpreter (although I don't know that anyone is working on that), and probably lots of other stuff.

As someone who has been intimate with the interpreter, I think I can reasonably say:

1 -- The internals need a major rewrite. The code having to do with interpreting files and interpreting MDI commands needs to be redone. The lifetime of global(named) parameters needs to be cleanly defined -- as does the lifetime of subroutine names.

2 -- The language needs an update (but could still be compatible). When I added o-words to the language, I took a quick and dirty shortcut by requiring (for example) that Onnn if and Onnn endif have matching nnn. There is really no need for that. An endif should be matched with the closest if or else. This was just a quick hack to avoid having to build a real parser. Error detection and reporting needs to be more complete and consistent.

The LinuxCNC people will not accept any changes that are not complete, tested, integrated, and ready for production use. I think that's quite reasonable.

The  machinekit people want to get this new stuff done. They don't want to wait to get their changes integrated.

So if you want something with more polish, a cleaner web site, etc, you might want to stick with LinuxCNC. If you want to be closer to the bleeding edge, go with machinekit.

Or better yet, be willing to switch back and forth, depending on your specific requirements at the time. Both projects are filled with dedicated people who are willing to go out of their way to support their users.

Regards,

Ken

--
website: http://www.machinekit.io blog: http://blog.machinekit.io github: https://github.com/machinekit
---
You received this message because you are subscribed to the Google Groups "Machinekit" group.
To unsubscribe from this group and stop receiving emails from it, send an email to machinekit+...@googlegroups.com.
Visit this group at https://groups.google.com/group/machinekit.
For more options, visit https://groups.google.com/d/optout.

--

Kenneth Lerman

55 Main Street

Newtown, CT 06470

[John Kasunich]

On Tue, Apr 26, 2016, at 09:48 AM, Kenneth Lerman wrote:
> My understanding of why the fork occurred is:
> 1 -- LinuxCNC has a goal to just work. It must continue to work, it must be
> easy (and get easier) to install, use, update, etc.
> 2 -- Machinekit would like to replace all of the ancient cruft that exists
> because it has always been there with new, modern, flexible, clean,
> understandable technology. It isn't important if that causes temporary
> dislocations where transitions are difficult. If the documentation doesn't
> keep track with the release, that's OK.

To add a bit to what Ken wrote - machinekit is also more interested in
supporting a wider variety of real-time operating systems. LinuxCNC
has an RTAI kernel that works very well and is very easy to use on a
conventional PC. Machinekit supports RTpreempt and also has ARM
support for platforms like the BeagleBone.

I'm primarily a LinuxCNC guy, but I want to do some things with a
BeagleBone instead of a regular PC, and Machinekit works better for that.
As Ken points out, the documentation for machinekit lags well behind the
code, something I find very frustrating.


--
John Kasunich
jmkas...@fastmail.fm

[Claudio Lorini]

Nice syntesis! 

i agree.

On Tuesday, 26 April 2016 15:48:41 UTC+2, Kenneth Lerman wrote:

....

So if you want something with more polish, a cleaner web site, etc, you might want to stick with LinuxCNC. If you want to be closer to the bleeding edge, go with machinekit.

...

[Kenneth Lerman]

I accidentally sent this to just John. Can the powers that be change the default so that reply goes to the list?

Ken

---------- Forwarded message ----------
From: Kenneth Lerman <ler...@se-ltd.com>
Date: Tue, Apr 26, 2016 at 11:58 AM
Subject: Re: [Machinekit] Re: New users try out Machinekit -- You won't believe what happens next!
To: John Kasunich <jmkas...@fastmail.fm>

If you find the documentation isn't complete, or is wrong  (not directed to John, as I'm sure he knows -- because he does contribute all the time), you shouldn't consider this a problem. You should consider it an opportunity -- an opportunity to contribute and make the job of the next person easier.

Please. In a well functioning, healthy, community, everyone contributes a small amount. And gets a large amount back.

Regards,

Ken

--
website: http://www.machinekit.io blog: http://blog.machinekit.io github: https://github.com/machinekit
---
You received this message because you are subscribed to the Google Groups "Machinekit" group.
To unsubscribe from this group and stop receiving emails from it, send an email to machinekit+...@googlegroups.com.
Visit this group at https://groups.google.com/group/machinekit.
For more options, visit https://groups.google.com/d/optout.

--

Kenneth Lerman

55 Main Street

Newtown, CT 06470

[John Kasunich]

On Tue, Apr 26, 2016, at 12:07 PM, Kenneth Lerman wrote:
>
> If you find the documentation isn't complete, or is wrong (not directed to
> John, as I'm sure he knows -- because he does contribute all the time),

To clarify - I was an active contributor to LinuxCNC. I haven't contributed
anything to machinekit (yet). I have thought about fixing up some docs,
but I've been busy with other stuff (haven't touched my beaglebone in
several months), and I haven't figured out how to get over the initial hump
of setting up a build system and github account.

> you
> shouldn't consider this a problem. You should consider it an opportunity --
> an opportunity to contribute and make the job of the next person easier.

Agreed. I just wish the initial hump was smaller. It's pretty easy to load
a precompiled image and start using things. Setting up to do builds and
pull requests and all that stuff is much more complex.

> Please. In a well functioning, healthy, community, everyone contributes a
> small amount. And gets a large amount back.
>

--
John Kasunich
jmkas...@fastmail.fm

[sliptonic]

On Tuesday, April 26, 2016 at 11:07:03 AM UTC-5, Kenneth Lerman wrote:

If you find the documentation isn't complete, or is wrong  (not directed to John, as I'm sure he knows -- because he does contribute all the time), you shouldn't consider this a problem. You should consider it an opportunity -- an opportunity to contribute and make the job of the next person easier.

Please. In a well functioning, healthy, community, everyone contributes a small amount. And gets a large amount back.

Regards,

Ken

With all due respect, Ken, this gets at my my main point but misses it.  The problem isn't an unwillingness to contribute, it's a lack of effective tools and structure for doing so.  The linuxcnc community has lots of user participation on the forums, wiki, IRC, and other venues.  While it's extremely easy to contribute, they suffer from a huge amount of bad, conflicting, out-of-date, and poorly maintained information.  

Machinekit seems to have chosen a minimal toolset (No IRC, no wiki, no real forum) to avoid this problem but now suffers from a different problem; the toolset is so limited or difficult to use that people aren't willing or able to contribute effectively.  Moreover, they're not able to organize themselves to tackle these very problems.  

For example, the process for writing documentation is still unclear (at least to me). Even the goals for documentation are not clear (man pages? ASCIIDOC? Markdown? github? readthedocs?)  Should a bunch of willing suckers agree to form a task force to tackle this, their discussion will exist right in the middle of the Google group with no categorization or focus because no tools exist for doing that.   

If you want power users to contribute, you have to give them a place to work, guidance, and tools.  

[Bas de Bruijn]

hi Guys,

I’ve had some time to think, and see some responses.

Straight from the chest, no blame, my own opinion and some personal introspection.

If I were to summarise:

(1)

I think the big issue here is that it’s unclear where certain types of documentation can be found

(2)

people are being put off because of the format (not readable/searchable enough)

(3)

people don’t have “noob” instructions. i.e. the hurdle to get started is too high when the BBB image is flashed

(4)

people think that adding to the documentation is hard.

(5)

But most importantly, I think that there is a big mismatch on what people (I hate these “labels” but I mean “Developers” )  think that other people (label: Beginners) need and can find.

Here’s my view:

For ma as a mechanical engineer, I had a huge learning curve 2 years ago. Understanding HAL and at the same time understanding linux related stuff, as well as trying to program was hard. If the Beaglebone weren’t there I wouldn’t have come as far (and more confident) as I’m now. Right now I’m confident with writing components, the cython bindings help me out, I’ve made a qtquickvcp remote UI, and I can handle GIT.

pretty impressive if I may say so myself. Have I had help? yes, big time! But in the end it was me that asked questions, blundered along, and got corrected.

Machinekit is a project which undergoes some pretty hard changes, while still trying to maintain the current CNC functionality. That’s actually a very hard thing to do. Changing the fundaments, while making sure that the walls don’t collapse.

I’m not sure if people are aware that the people doing this can be counted on 1 hand. Although luckily lately we have a few fingers.

And the important thing to understand: There’s nobody giving forcing direction in a sense that it accepts all changes if one has a need to fix something. http://www.machinekit.io/about/

Developers don’t understand what the average beginner encounters. So they are IMO the guys that can help others. And that means that the others (beginner) need to ask questions (define the problems).

I don’t believe in a task force that will set everything back on the right track. Because my fear is that this task force will be the same people that have done a lot of work in the past.

I’m fairly self critical, and I share the opinion that the documentation needs to be improved. Fancy rendered, and easy to update by everybody. Better ways of asking questions? Wonderfull ideas and I’ll provide input/feedback where I can.

BUT

(a)

I (and maybe other people too) don’t know what’s needed, otherwise It would already have been in place

(b)

I don’t have the fuel to take on such a thing (pull the cart) because I feel I’ve been running into a wall the past 1.5 years with documentation. For who should I do that, why should I care, and what does it bring me? Help? Sharing the load? I’m very glad with the help of Mick and if it wasn’t for him I would stop touching documentation a long time ago.

I think the biggest oversight from the Machinekit Project (in no way a single persons fault) is to provide the structure for a community. And I’m as much at fault as anybody. I think we can all agree that Brad has found a problem which needs to be addressed.

just some links to see what’s already there (yes I know, you have know where to look):

git instructions on updating your fork, so one can update a cloned fork and make PR’s

some instruction on a machine setup

Please keep up this discussion! I really appreciate a critical mindset and constructive feedback

Bas

p.s.

the reason the ROS stuff stopped, was not that the issue closed, it was because I haven’t continue working on ROS and Machinekit again. Happy to share some of my knowledge, but If nobody asks I think that nobody needs ROS + Machinekit (same goes for the ROS community)… I’m not a preacher, plus I have a wife and family, so my time is valuable.

[Charles Steinkuehler]

On 4/26/2016 2:25 PM, Bas de Bruijn wrote:
>
> the reason the ROS stuff stopped, was not that the issue closed, it was because
> I haven’t continue working on ROS and Machinekit again. Happy to share some of
> my knowledge, but If nobody asks I think that nobody needs ROS + Machinekit
> (same goes for the ROS community)… I’m not a preacher, plus I have a wife and
> family, so my time is valuable.

Work on ROS hasn't stopped, I think it's just paused for a bit.

Bas, IIRC you have "smart" motor drives that handle homing for you, so
all you need to move things is the existing ring-buffer. I have been
working more on the hardware side, getting some boards from Mesa
(arrived) and making my adapter board to hook them to the DE0-Nano
SoC+FPGA (OSH Park just sent me an email saying they shipped).

I will be working on getting ROS working with my robot arm via the
DE0-Nano, so look for more progress (and requests for help setting up
a ROS configuration) soon!

If anyone else is interested in working with Machinekit and ROS, most
of the pieces are now available to experiment with if you're
comfortable working with HAL components and custom ROS configurations.

--
Charles Steinkuehler
cha...@steinkuehler.net

[Charles Steinkuehler]

On 4/26/2016 2:25 PM, Bas de Bruijn wrote:

> Developers don’t understand what the average beginner encounters. So they are
> IMO the guys that can help others. And that means that the others (beginner)
> need to ask questions (define the problems).

I've always said the best way to get a developer to write
documentation is to ask them the same questions over and over.

Eventually, it gets annoying enough some documentation gets created!

:)

> I don’t believe in a task force that will set everything back on the right
> track. Because my fear is that this task force will be the same people that have
> done a lot of work in the past.

One of the things I like best about the initial post on this thread is
it's an honest view from "outside" the project. I (and others here,
I'm sure) frequently don't try to access the website or documentation,
so are not fully aware if step-by-step instructions are broken, or if
it's unclear exactly where to file a bug or how to install from source.

There's definitely some "low hanging fruit" we can fixup pretty
quickly, and I know a major revision of the documentation is currently
underway. I think we also need to communicate exactly what Machinekit
is (and isn't) and where we are trying to go, which has been slightly
fluid over the short life of the project.

--
Charles Steinkuehler
cha...@steinkuehler.net

[Norbert Schechner]

For who should I do that, why should I care, and what does it bring me? Help? Sharing the load?

Hallo Bas,

for people like me, willing to contribute. I have taken several tries to get a development system up and running, machinekit was not the big problem, at my first tries, but getting QtQuickVCP to work, I have not been able. I have not asked much either, as at the beginning it was just playing.
But nevertheless I tried to maintain gmoccapy also under machinekit (I need to update again, sorry for the delay).

I will not give up so quick, but the basic documentation like getting started, must be on all time up to date, at right now it isn't. (See the kernel install problem).

My goal is a gmoccapy for machinekit, based on Qt. Do machinekit need/want such a "tool / GUI" ?

Norbert

[John Kasunich]

On Tue, Apr 26, 2016, at 04:24 PM, Charles Steinkuehler wrote:
> On 4/26/2016 2:25 PM, Bas de Bruijn wrote:
> > Developers don’t understand what the average beginner encounters. So they are
> > IMO the guys that can help others. And that means that the others (beginner)
> > need to ask questions (define the problems).
>
> I've always said the best way to get a developer to write
> documentation is to ask them the same questions over and over.
>
> Eventually, it gets annoying enough some documentation gets created!
>
> :)
>
> > I don’t believe in a task force that will set everything back on the right
> > track. Because my fear is that this task force will be the same people that have
> > done a lot of work in the past.
>
> One of the things I like best about the initial post on this thread is
> it's an honest view from "outside" the project. I (and others here,
> I'm sure) frequently don't try to access the website or documentation,
> so are not fully aware if step-by-step instructions are broken, or if
> it's unclear exactly where to file a bug or how to install from source.

I still plan to get back to my "step-by-step HAL-only config on a BBG"
project, which I was documenting in a thread on this list. I will resume
that thread when I do.

> There's definitely some "low hanging fruit" we can fixup pretty
> quickly, and I know a major revision of the documentation is currently
> underway. I think we also need to communicate exactly what Machinekit
> is (and isn't) and where we are trying to go, which has been slightly
> fluid over the short life of the project.

One bit of such low-hanging fruit is something that I'll do if I ever get
over the setup hump. During my project, I posted an example using
the threads component to create a real-time thread. Micheal replied
that the threads component is no longer needed - there is now a
HAL command to create a thread. Sure enough, I looked at the source
and there it is.

Then I looked at the man page. Nope, not a word.

Then I looked at the built-in help in halcmd, where every command
is documented. Nope, not a word.

My immediate thoughts were that someone did half the job. They
wrote the code to implement the command, but didn't update the
built in help (in the same source file!) or the man page.

Then I thought "cool, someplace where I can make a contribution".
Only problem is that to fix the built-in help I need to be able to
build from source. On the BBG that will be at best painfully slow.
On my other Linux boxes it may or may not be possible (I have
ancient Linuxes and there are probably dependencies that I don't
have installed). I could probably change the man page with less
effort, but I don't want to do half the job.

John

[Charles Steinkuehler]

On 4/26/2016 3:32 PM, John Kasunich wrote:
>
> Then I thought "cool, someplace where I can make a contribution".
> Only problem is that to fix the built-in help I need to be able to
> build from source. On the BBG that will be at best painfully slow.
> On my other Linux boxes it may or may not be possible (I have
> ancient Linuxes and there are probably dependencies that I don't
> have installed). I could probably change the man page with less
> effort, but I don't want to do half the job.

Just because you're using halcmd on the BBB doesn't mean you have to
build it there. You can build and send a PR from an x86 environment,
which will get build-tested on armhf when you file a PR.

It's also possible to cross-compile on the x86 and target the armhf if
you want to test on the 'Bone, but it's kind of a pain to get setup.
There is work in-progress for Docker containers that would make this
*MUCH* easier, but I don't think it's quite finished yet.

...but in general, building on the BBB is an exercise in frustration,
particularly if you don't add a fair chunk of swap partition. You
really don't want to be building natively unless you have at least
something like a CuBox or Wandboard. That's probably another good
thing to mention on the website!

--
Charles Steinkuehler
cha...@steinkuehler.net

[thematsche]

On 2016-04-26 22:24, Norbert Schechner wrote:
>
>> My goal is a gmoccapy for machinekit, based on Qt. Do machinekit need/want
>> such a "tool / GUI" ?

YEP!

>> Norbert
>>

Matsche

[Bas de Bruijn]

> On 26 Apr 2016, at 22:15, Charles Steinkuehler <cha...@steinkuehler.net> wrote:
>
>> On 4/26/2016 2:25 PM, Bas de Bruijn wrote:
>>
>> the reason the ROS stuff stopped, was not that the issue closed, it was because
>> I haven’t continue working on ROS and Machinekit again. Happy to share some of
>> my knowledge, but If nobody asks I think that nobody needs ROS + Machinekit
>> (same goes for the ROS community)… I’m not a preacher, plus I have a wife and
>> family, so my time is valuable.
>
> Work on ROS hasn't stopped, I think it's just paused for a bit.

Ah, yes, you're correct. I mostly referred to that specific thread :) which had had its use and the new issue is much more focused

>
> Bas, IIRC you have "smart" motor drives that handle homing for you, so
> all you need to move things is the existing ring-buffer.

Yes, I didn't have to worry about homing from HAL. But that is a separate thing. The way the ringbuffer (HAL) gets filled with trajectory segments is the "integration" aka the bridge between ROS and MK.

> I have been
> working more on the hardware side, getting some boards from Mesa
> (arrived) and making my adapter board to hook them to the DE0-Nano
> SoC+FPGA (OSH Park just sent me an email saying they shipped).
>
> I will be working on getting ROS working with my robot arm via the
> DE0-Nano, so look for more progress (and requests for help setting up
> a ROS configuration) soon!
>
> If anyone else is interested in working with Machinekit and ROS, most
> of the pieces are now available to experiment with if you're
> comfortable working with HAL components and custom ROS configurations.

Yes! The base is available. We need applications that handle homing, jogging etc!

[John Kasunich]

On Tue, Apr 26, 2016, at 04:39 PM, Charles Steinkuehler wrote:

>
> Just because you're using halcmd on the BBB doesn't mean you have to
> build it there. You can build and send a PR from an x86 environment,
> which will get build-tested on armhf when you file a PR.

Understood. In this case, all I'm doing is adding some built-in help to
halcmd, so I can test on any platform. But it would be nice to have my
bug-fix (minor as it is) on the system I'm running.

> It's also possible to cross-compile on the x86 and target the armhf if
> you want to test on the 'Bone, but it's kind of a pain to get setup.
> There is work in-progress for Docker containers that would make this
> *MUCH* easier, but I don't think it's quite finished yet.

As a casual user, there is no way in hell I want to mess around with
cross-compiling.

> ...but in general, building on the BBB is an exercise in frustration,
> particularly if you don't add a fair chunk of swap partition. You
> really don't want to be building natively unless you have at least
> something like a CuBox or Wandboard. That's probably another good
> thing to mention on the website!

I figured that was the case, glad to have the confirmation.

Sadly, building on an x86 system probably won't be smooth sailing
either, since my most likely candidate is still running Ubuntu 6.06.


John Kasunich
jmkas...@fastmail.fm

[Charles Steinkuehler]

On 4/26/2016 3:44 PM, John Kasunich wrote:
>
> On Tue, Apr 26, 2016, at 04:39 PM, Charles Steinkuehler wrote:
>
>> Just because you're using halcmd on the BBB doesn't mean you have to
>> build it there. You can build and send a PR from an x86 environment,
>> which will get build-tested on armhf when you file a PR.
>
> Understood. In this case, all I'm doing is adding some built-in help to
> halcmd, so I can test on any platform. But it would be nice to have my
> bug-fix (minor as it is) on the system I'm running.

Once your PR gets accepted, you should be able to install the new
Machinekit packages on any supported system within an hour or so (the
time it takes for all the production package builds to complete and
get pushed to the package repo) with a simple apt-get update / apt-get
upgrade.

For simple stuff like compiled-in usage or docs, you can even use the
PR build tests as your dev-system. Just push your edits, see if the
push builds cleanly, and edit as required. Not as quick as a local
build, but you don't have to setup a full dev. environment for a
simple one-off fix.

--
Charles Steinkuehler
cha...@steinkuehler.net

[sliptonic]

I have a robot that I can't control, a book that I haven't finished reading, and a willingness to try anything once.  

You'll have to lower the acronym density and ELI5 but I'm game.

Last time I looked ROS wanted only to be installed on Ubuntu and Machinekit strongly preferred Debian.  Still true?

[Charles Steinkuehler]

On 4/26/2016 5:15 PM, sliptonic wrote:
>
> Last time I looked ROS wanted only to be installed on Ubuntu and Machinekit
> strongly preferred Debian. Still true?

In general, but there's an official push to get ROS running on Debian,
and there's also the use case of ROS running on an x86 Ubuntu
platform, with a minimal ROS + Machinekit install running on something
like the BBB or SoC+FPGA and communicating via Ethernet.

I'm probably going to setup an Ubuntu install with a PREEMPT_RT
real-time kernel and a Mesa card to control my robot arm, and work on
swapping out the Mesa card for a (remote) DE0-Nano SoC+FPGA. But
first I have to get _something_ actually moving with ROS. ;-)

--
Charles Steinkuehler
cha...@steinkuehler.net

[Tom M]

The Ros thing had popped up on my radar screen a few months ago from a project a co-worker was working on..   I also have a university contact who is involved with Ros development who was unaware of machinekit kit till I mentioned it to him.

Is there a blog post or something that you could point me to as far as what you guys have been up to with this and where you want to go, that I could forward to him?

--
website: http://www.machinekit.io blog: http://blog.machinekit.io github: https://github.com/machinekit
---

You received this message because you are subscribed to a topic in the Google Groups "Machinekit" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/machinekit/fcrZiX4OGpc/unsubscribe.
To unsubscribe from this group and all its topics, send an email to machinekit+...@googlegroups.com.

[Bas de Bruijn]

I have a ROS + Machinekit install on Ubuntu, and also a Debian Jessie VM with ROS and Machinekit. The ROS on Jessie is still compiled from source (Because I've been following ROS industrial tutorials), and not all packages are supported yet on Debian.

Michael some time ago made a exploratory BBB image with MK + ROS, and I’ve used that (plus a node which puts trajectory segments into the HAL ringbuffer) to run motors...

see https://youtu.be/IljDRPuKq_E

this setup above runs ROS master on my PC, generating trajectories on a muscular PC, and the BBB+Cramps listen to that trajectory (standard ROS remote functionality). The thing is that you don’t want an ARM device like BBB do planning stuff. And that doesn’t have to be done. You can for example play out recorded movements from a python script like you would play a music file.

I’ve got on my to-do list to get a basic demo of ROS into the Machinekit SD image, but I’m sidetracked with manpages and asciidocs at the moment (sorry, this male can’t multitask).

Beware: ROS has a learning curve (I’m still at it), so I’d advice to do the ROS-I tutorials anyway (http://aeswiki.datasys.swri.edu/rositraining/indigo/Exercises/). That gave me a basic understanding on what happens. If you want your own robot, and the planning (collision detection) of ROS and whatnot then there’s no one click setup option. You’ll have to get your hands dirty with ROS.

I hope people are wanting to set up a system and explore ROS + Machinekit. So after the current manpage/documentation distraction I’ll get back to get an example setup + step-by-step guide on how to set this up. I’ll rely on feedback to know if I ELY5 w.r.t. the ROS -> Machinekit HAL rosnode

[Yishin Li]

On Tuesday, April 26, 2016 at 12:04:23 AM UTC+8, sliptonic wrote:

Github Issues.

I was really interested to follow the Machinekit + ROS initiative and somehow I got subscribed to the github issue.  Very cool stuff!  Then the discussion just disappeared because the issue was closed.  There was no summary, blog post, documentation, or roadmap.  If the work continues, I'm unaware.

I don't think the issue tracker itself needs to change, but somehow the end-user implications need to make their way to end-user outlets.

Because I was interested in the MK+ROS thing, I went hunting. Issue #689 got almost 200 comments often averaging 5-10 per day.  Once closed, issue

#898 should have taken its place.  So far, it hasn't received a single comment.  By closing the issue, we lost all the momentum but we also lost all the community that had formed around the issue.  If someone had commented on the original, they were auto-subscribed and got updates but that disappeared when the issue was closed.

Bottom line:  Tons of useful information gets buried in the discussion and never sees the light of day. Issues don't work for long-term initiatives because either the community is destroyed when the issue is closed, or the issue grows without structure forever. For all the good info buried in the issue discussions, an end user wouldn't even know to search there.

FYI, I was working on a project to tryout ROS and Machinekit with industrial robot (RA605). It is with 6 joints of ac servo motors with absolute encoders. The ROS and Machinekit software are running on a Raspberry Pi2. Here's the link for software setup guide and electrical wiring diagrams:
http://en.araisrobo.com/products/ar1160/app-notes

-Yishin

[Tom M]

Thanks for the link, I forwarded it to the professor I know, who does a lot of work with  Ros.  

Btw, I 've been keeping some pretty detailed notes, on the things I've been dealing trying to get my MPCNC project going..

I'm trying to get this project done for next week (not looking good at the moment,)   I can refactor it into a user getting started guide...   I don't have the time at the moment to really study in detail all the conversation from Brads initial comment but  it looks very interesting.       The wiki thing sounds interesting..   Has anyone played with Creole?  https://en.wikipedia.org/wiki/Creole_%28markup%2s

I think once I get my MPCNC project done, I would mind educating myself in Ros.   I wouldn't mind designing a robot that could be 3d printed  which could use a beaglebone  Machinekit/Ross.

Tom

--

[Michael Brown]

Dear @ sliptonic

Your original post here touched a deep note in me so I will repost a concept it has been difficult for me to express clearly from the beginning without having to return and reformulate and rethink it several times after it was inflated and shot down several times in that process:

Nevertheless:

Ironically the original mksocfpga idea and agreements about how to get started are hidden in this forum in a hijacked thread like this one (in august), I very much would like to get this thread back on track.

I have a very different perspective that most and the futility of being able to prevent all the documentation I have been generating during this long development phase of manifesting the mksocfpga idea from a vague idea that seemed potential into becoming as substantial and comprehensive as it is today, form laying scattered around in various different places, fragmented unlinked and now impossible to gather and track down for putting into the mk doc repo.

The short version:

The whole C4 structure around Machinekit seems to be built around:

Please start by stating / formulating the problem you wish to solve as an issue.

However when I wish to exchange notes and instructions for how to do this and that or create more verbose versions of this and there for are into providing some sort of explanation that already is in my mind 

and needs a placeholder to be put into for turning it into more solid documentation later on.

That place holder is missing and even the idea of having something available right next to the the issue tracker I'm communicating on.

However with the most critical important difference that the first requirement here is please state the name / title of your solution / fix guide.

And then I can offload that specific info while I have it fresh in my thoughts and then link that back to the problem solve issue solve thread.

And after the problem has been solved and the issue thread is closed as resolved.

Then the remaining documentation suggestions that lead to solving the problem are remaining as the left overs that must have been missing in the documentation. And so should be added to the documentation 

ASAP, so they dont have to be retyped again.

Remember first requirement is to look in the documentation before creating a new issue ...?

And problem solving issues are not meant as placeholders for solutions  only links to solutions.

-----

#929 header quote:

Problem1:

When working on solving an issue a contributer will often face questions like
the ones in this new thead I will use as an example below in message nr2:

The type of questions boil down asking for guidelines of how to do a spesific task.

Problem2:

The issue tracking system in not a good starting point for:

proposing a solution (howto style or faq style)

adding new documentation.

or proposing corrections for already existing information. 

There is a different energy to providing, answers, guides and all related types of online info than the issue tracker is built for.

Meaning to add to the documentation you come with an how can I share this information or knowledge so that others can understand if frame of mind.

The Issue tracking requirement of: 

Please formulate the problem that need to get fixed first,,,,

Acts as a major turn-off as that is not anyway near what you came to do, and now you suddenly have
the new problem that you did not have one in the first place.

As you came to share something instead.

---

 

On Monday, 25 April 2016 18:04:23 UTC+2, sliptonic wrote:

Sorry for the long read that follows (and the click-bait subject). I think all of this is part of a single issue of user-friendliness that needs to be addressed together.

It's a Sunday afternoon and I'm sitting here trying to catch up on things in the Machinekit world and I'm facing the same frustration I faced six months ago.  And a year ago.  And a year and half...

I'm left with the distinct impression that Machinekit is not a user friendly project.  To be sure, the project is full of very friendly people but the project itself has a systemic problem that doesn't seem to be improving with time.  This was completely understandable when the project was new and just getting its legs but we're now more than two years on and things don't seem to be improving.

I think that this is a pressing problem because it means we aren't bringing new users to the project.  More importantly, we aren't creating that class of 'power users' that, in other open-source projects, provides support, writes end-user documentation, and files bug reports.

While Machinekit has an uncompromising focus on writing excellent software, there's almost no effort at making the project more approachable, or flattening the learning curve.  I'll cite a handful of specific example to make my point:

Main website

The website should do three things; 1) tell people what Machinekit is.  2) Help them understand the current state, organization, and direction. 3) Point them to more effective resources depending on their needs.  The current website does a poor job at all three.

- Go to the project page machinekit.io.  Click the 'blog' link.  It looks like you've entirely left the site! There's No consistent look or navigation.  Try to go back to the main page.  You have to use the browser back button because there's no link at all.  If you come in from an external link, you have to hand-edit the url to get to the main page.

- The top navigation is completely arbitrary.  Why are there links to github but not to packages? The two top/left links (and 3 of the 5 menu items) are of no use to an end user at all.

- The blog is the most interesting part.  It is rarely updated.  As of this writing, the first three posts are hardware related and the most recent status post is November of last year.  A monthly or quarterly report of status would be a vast improvement.

- The About page says nothing about the history or origin of the project.  If a user hears that MK is a fork of linuxcnc, they have no idea why the fork was needed, what the goals of the new project are, or what the relative merits of the project are.

Official Documentation

I know documentation has been getting some focus lately but right now it's a mess.

- I did a  google search for 'machinekit documentation'.  #1 result doesn't go to the github docs but to the project documentation page.  From there, the most useful link is the 6th one down (after the blog and the issue tracker) and buried in text.  As an end-user, I know I'm expected to 'RTFM' but I can't tell which 'FM' the project expects me to 'R'.

- The #2 Google result goes to readthedocs.  Once there, The first link tells me to 'always read the README file first'.  Unfortunately, the README link is 404. I'm not joking.  The first link in the official documentation is broken.

- Using github as a system-of-record is really smart from a development point of view but it raises the friction for end-user contribution. If we're not going to use a wiki for documentation, then we have to have a tool-set that is at least as easy to use. The alternative is that documentation is maintained almost exclusively by the developer community.

- Overall, the documentation quality is pretty bad.  Even some of the machinekit specific stuff is out of date or broken.  Documentation is heavily weighted to traditional 'man page' style and very light on real-world examples that a user could copy and learn from.

Bottom line: I think the overall friction to contribute is really high and the results reflect this. if we're going to stick with git, we're going to have to lower that friction. A lot.

Google Group

By far, the most useful resource for MK is the google group.  Almost any issue a new user is likely to face has already been addressed.  But it's flat.  There's no categorization or structure so a user has to just start reading or searching.  Searching depends on knowing the right keywords so success is variable.

Just reading the group is very informative but the discussion is overwhelmingly developer centric.  A new user will be intimidated and reluctant to even ask a question.

If user frustration is high enough and they ask a question, they generally get help but that burden is landing squarely on developers shoulders.  Just in the last couple days I saw a new user startup thread that went to 25+ replies.  It was all pretty basic stuff about setting up a BBB but was almost entirely Bas and Charles answering.  (Did I mention the project is full of nice people :-)

An anecdote:  A couple months ago, I recommended MK to a friend who was doing a mill conversion.  I talked to him a couple weeks later and was surprised to hear he went with LinuxCNC.  When I asked why, he expressed frustration with the resources.  Since his conversion was pretty basic, He went looking for specific examples to copy. Unable to find anything, he decided he didn't have time to wade through years of Google group posts to try to figure it out.  This guy is a professor of electrical engineering at the University.

Bottom line: The google group feels useful but in a lazy way.  It puts all the burden on the end user. No sticky topics, no tag clouds, nothing that helps a user navigate the fire-hose of information.  It's all or nothing.  Content isn't separated by demographic (Users vs developers) or interest area (GUIs, HAL, etc), architecture (PC, BBB, RaspPi), application (robots, drones, mills, etc) or anything else.

Github Issues.

I was really interested to follow the Machinekit + ROS initiative and somehow I got subscribed to the github issue.  Very cool stuff!  Then the discussion just disappeared because the issue was closed.  There was no summary, blog post, documentation, or roadmap.  If the work continues, I'm unaware.

I don't think the issue tracker itself needs to change, but somehow the end-user implications need to make their way to end-user outlets.

Because I was interested in the MK+ROS thing, I went hunting. Issue #689 got almost 200 comments often averaging 5-10 per day.  Once closed, issue

#898 should have taken its place.  So far, it hasn't received a single comment.  By closing the issue, we lost all the momentum but we also lost all the community that had formed around the issue.  If someone had commented on the original, they were auto-subscribed and got updates but that disappeared when the issue was closed.

Bottom line:  Tons of useful information gets buried in the discussion and never sees the light of day. Issues don't work for long-term initiatives because either the community is destroyed when the issue is closed, or the issue grows without structure forever. For all the good info buried in the issue discussions, an end user wouldn't even know to search there.

Other Community.

I'm sure there are people doing interesting things with MK and maybe blogging about it but I can't find them. The Machinekit project is doing a spectacular job with the software, but the human side is getting neglected. Although there was (is) a lot of things wrong with the LinuxCNC project, I miss how easy it was to ask questions, learn from each other, and make friends.

Am I alone in my frustration?

-sliptonic

-- 

Brad Collette
573-427-7132

[Brad Collette]

Michael,

I'm not sure I understand the details of the problem you're pointing to.  Do you think this is a problem with the tools or with the methodology?

In other words, do we need to find better tools to capture documentation as it is being created or do we need a policy change for how to use the issue tracker?

--
website: http://www.machinekit.io blog: http://blog.machinekit.io github: https://github.com/machinekit
---
You received this message because you are subscribed to a topic in the Google Groups "Machinekit" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/machinekit/fcrZiX4OGpc/unsubscribe.
To unsubscribe from this group and all its topics, send an email to machinekit+...@googlegroups.com.
Visit this group at https://groups.google.com/group/machinekit.
For more options, visit https://groups.google.com/d/optout.

--

Brad Collette
573-427-7132

[Michael Brown]

Thanks Brad

I am trying to describe something new that I see as missing, and needs to be added in terms of functionality.

So I think it best to leave the tool discussion aspect out of this more abstract idea development phase, and lean towards

formulating a new tool defined as a clone of the current github issue tracker, but with a different name, purpose and guidelines for usage:

So I will here describe it as the docu tracker.

Purpuse:  

To track information related to 1 subject / topic.

To be the starting point for new texts, images, diagrams, guides, readme's etc

For any repo commit related effort to add development notes and other usage information that needs to be shared.

When to close this docu tracker topic:

When the snipplet has been finish edited and commited into the doc repo / database.

BTW:

The text in these snipplets, do not contain any font or colour information / formatting, (but may contain header / body / paragraph / footer info etc)

Like the current issue tracker's header locks the thread to only contain a formulation of the outcome in terms of a problem that needs to be solved.

and then the issue is closed.

It now seem very clear to me that what is missing is something likewise, but with focus in:

Define what is is you want to describe, in terms of 1 exact topic.

This tracker / new tool, should then be able to pipeline the --> editing --> commit to doc repo. --> ascii doc or whatever presents the info best.

IMHO creating md style docs I very easy and understandable to do also for a newcomer.

I hear a lot of noise about fragmented snippets of documentation, leading to all sorts of problems.

I can only think these thoughts origin from that the concept of the docu tracker must be new and therefore as unknownmust be

presented as something new and unknown and described very carefully and detailed in terms of functionality and purpose only.

Not in terms of known tools.

It is very obvious to me that any technical manual can be produced by inserting (links of) snippets describing each 1 specified

topic formulated as having the purpose of providing that information / note / image / piece of code / presentation etc 

 

So I just sense there is some sort of disagreement about how best to start putting documentation online while developing for a github repo.

And a doc commit / tracking keeping track of doc topics in terms of "loose" 1 item / subject topics paragraphs, in type of indexed database like structure..

Would be the very best way to begin sharing repo related information.

[Michael Brown]

Note:

Also when that topic needs an update, the docu issue can then be reopened, as long as it server active information.

THen lastly is needed a rule for when to hide or permanently delete that docu snipplet and its tracker from the database.

[sliptonic]

So I think it best to leave the tool discussion aspect out of this more abstract idea development phase, and lean towards 

formulating a new tool defined as a clone of the current github issue tracker, but with a different name, purpose and guidelines for usage:

Just to be clear: Different name, purpose, and guidelines but identical functionality?

 

So I will here describe it as the docu tracker.

Purpuse:  

To track information related to 1 subject / topic.

To be the starting point for new texts, images, diagrams, guides, readme's etc

For any repo commit related effort to add development notes and other usage information that needs to be shared.

When to close this docu tracker topic:

When the snipplet has been finish edited and commited into the doc repo / database.

Is this not identical in intent and usage to the current github issue tracker for machinekit-docs

It seems that the current fork-PR process will work.  Preliminary documentation would then exist in a private fork of machinekit-docs until a pull request is sent and accepted.  An issue in the machinekit-docs issue tracker should contain a link to the private repo so a searcher can find it.

This does raise the issue of multiple issue of multiple issue trackers.  To be honest, the problem exists already:  These are the current github repos under the machinekit organization with the count of issues in their respective trackers:

machinekit-docs - 7

machinekit - 118

mksocfpga - 5

mk-builder - 4

machinekit-dkms - 1

machinekit-ng - 1

machinetalk-protobuf - 12

machinekit.github.io - 7

mesanet-firmware - 0

nanopb - 0

machinekit-man - 0

I think shutting off all trackers except the machinekit tracker would be a mistake.  The issue you are pointing to shows the legitimate need for at least one more dedicated to docs.  However, I worry that issues in the other trackers will be overlooked or contribute to confusion.  

Anyone have any thoughts about this?

 

[schoo...@btinternet.com]

The problem with issue trackers is they become a chat room for those people involved in defining and trying to resolve an issue.
They also often go off at a tangent or become subject to 'mission creep'.

There may be pearls of wisdom in them, but if you get a long thread, I for one am not going to trawl it all in the hope of finding one.

If someone develops / writes / fixes something, it is their 'duty' towards the other users to document it so that others can use / follow it too.

How they do it it is one for them, incrementally or at the end, once the subject is done and dusted and the full picture can be seen is often best.

If cutting and pasting stuff from the issue thread, adding diagrams etc. is a good method for them, great.

However having a rigid system of 'issue tracker-trackers', that most people won't use or would not be appropriate to many issues, is not the way
forward IMHO.

It smells of documentation responsibility abnegation, "I did document it, its all in this obscure tracker-tracker ( in no particular good order )"

--
website: http://www.machinekit.io blog: http://blog.machinekit.io github: https://github.com/machinekit
---

You received this message because you are subscribed to the Google Groups "Machinekit" group.

To unsubscribe from this group and stop receiving emails from it, send an email to machinekit+...@googlegroups.com.

[Michael Brown]

OK I sense I am getting cold feet very much regretting ever using the issue tracker with a different functionality

as the reference of what im trying to convey.

I actually can see now that its not git functionality Im talking about, let me try to finish off the presentation:

Now the title of the docu issue is what is a definition of the topic in the very first post that act as the docu "commit".

being written and reformulated.

All comments are below.

When the wording is satisfactory the first message is then "committed" into the indexed database and comments are deleted.

Issue closed.

Now lets say someone needs to update that information:

Issue (text blob / docu blob, section...) reopened and that exact same content is the pulled out of the database,

for editing in the first post, commenting below if discussion is needed.

When reformulating is satisfactory:  issue (first message) commited, issue closed, comments deleted,,,,,

THis is totally different than the git method.

Code commits are interwoven and rely on each other to function correctly and are always added in a linear timeline fashion.

I am talking about chunks of small self contained  topics / subjects / descriptions / guides / full code example blocks / presentation headers ...etc...

  
Think: same interface but certainly not git as the commit engine ... ?

[Michael Brown]

Comment:

I think the note that was struck in me is an idea I caught on to several years ago formulated like:

Would it be possible to break a document / manual, into its smallest possible self contained paragraphs.

and then reassemble it by having page templates linking in the content / paragraphs.

At that time it did not seem realisable, but it has been running in my subconsciousness ever since as an thought experiment.

And now it suddenly pops up and asks to be presented because it is possible to make it work as a new tool here.

That is if it don't totally foul up presenting the concept of the unused / new idea properly...   

[Chris Morley]

I think a couple things that would help:
a wiki like linuxcnc has...the barrier to make docs is pretty low there.
Lots of the linuxcnc docs started as wiki pages, then transferred to the official docs by a volunteer or later by the developer after he figured out how.

a release of some kind.
A release focuses (forces) attention to the things required for an end user.
It also makes doc work and configuration programs worth the effort to write as they are not immediately out of date and useless.

 Chris M

[Bas de Bruijn]

Hi List.

I would like to ask for a constructive review of some work I’ve been doing the past weeks.

This is about one of the points in Brads original post where a lot of people seem to agree upon:

—> Lowering the barrier for new users in getting information.

I’ve merged the website and documentation, and we propose to display the documentation that’s in the github/machinekit/machinekit-docs repo on machinekit.io/docs in the future. Michael has set up some basic automation so that a PR will generate a site on preview.machinekit.io After a merge of a PR we then can update machinekit.io accordingly

So please go to preview.machinekit.io and give us feedback if this in your opinions will lower this particular barrier for new users.

Please be mindful of the fact that this still needs work (maintenance) to get into the right shape/structure. This is a rough draft.

This is not about “how to contribute (to the docs)” perceived barriers because that will still follow the fork-and-pull-request flow like we do now, and is IMO a separate problem.

Summary

- one place to go search/read up: machinekit.io

- correct visual presentation like “notes”, “info"

- Jekyll served with asciidoc sources, we aim at also making diagrams with Jekyll/Asciidoctor

- we still can generate PDF files and/or ePub files.

There are still a lot of loose ends (in no particular order):

- This is mostly the legacy manuals, rendered by Jekyll.

- get diagram functionality to work

- there needs to be proper sections/info on platforms, examples, setting up etc. (info partly available, structure needs work)

- searching thru the site docs info?

- link checking

- remove info that’s deprecated

- typeface, readability, CSS style

- generating PDF files/ePub

- faq? jekyll functionality?

I’m looking forward to all (non-trivial) feedback.

Cheers,

Bas

[sliptonic]

Bas,

I think this is a significant step forward.  The content will need lots of work (both hands and eyeballs) but getting the tools working is certainly step one.

Since the 'fork and pull-request' model might be new to some potential contributors, I think the documentation should include a "How to contribute to the docs" document.  As I was thinking about that, I said to myself, "OK, smartass,  why don't you get off your butt and write one?"  Faced with such a compelling argument, I tried... and got stuck.  

1) If a user recognizes that a need exists, how does he/she communicate the need to the community?  I think this needs to be an issue.  But where?  In the main machinekit issue db or the machinekit-docs issue db?  

2) How does the user know if the issue has already been reported?  I guess the user should be directed to search the db.  Or maybe the docs should contain an autogenerated summary of open documentation issues with links.

3) If the user finds an open issue, how does he/she know if someone is working on this?  Are we going to take advantage of the 'Assignee' field in the github issue tracker?  I don't think this will work.  I think it only refers to members of the Machinekit organization.  So the user would read the comments and determine if someone is working on the issue and has started a fork.

4) How does the user find preliminary (WIP) documentation?  I guess this is like #3.  The user reads the comments looking for a link to a fork where work is being done.  Better yet, the person working on the documentation has done PR marked with something like "WIP-DO NOT MERGE" so that the preview is generated but not merged.  

Here a proposal for a process. What do you think?

0) Random user reads documentation, sees deficiency, searches issue db, and realizes deficiency is real.

1) Random user (me), creates an Issue to flag need for a 'how to contribute to the documentation' document.

2) Someone in Machinekit community becomes the Assignee.  This doesn't mean they'll write the docs, just that they'll curate the issue and see that it eventually gets resolved.

Curation means making sure it has an appropriate subject line and links to relevant forks.  Curation also means speaking up if it appears the issue has gone stale.

3) Random user forks and edits.  Random user is (strongly) encouraged to do WIP pull-requests early and often to allow previews to be generated.

4) Random user eventually submits actual PR to close issue.

[sliptonic]

Edit.  I just found the current 'how to document'  Its a very good start and answers some of the questions below but doesn't address issues or WIP.

[Bas de Bruijn]

Hi Dave,

On 09 May 2016, at 14:58, sliptonic <shopint...@gmail.com> wrote:

Bas,

I think this is a significant step forward.  The content will need lots of work (both hands and eyeballs) but getting the tools working is certainly step one.

yes, I agree

Since the 'fork and pull-request' model might be new to some potential contributors, I think the documentation should include a "How to contribute to the docs" document.  As I was thinking about that, I said to myself, "OK, smartass,  why don't you get off your butt and write one?"  Faced with such a compelling argument, I tried... and got stuck.  

I know where to find this one. One reason I’d like to get the diagram functionality (sequence editor, and whatnot) to run is to be able to make a diagram, which says more than words. http://asciidoctor.org/docs/asciidoctor-diagram/#specifying-diagram-generator-paths

I once added an “update your fork” instruction, (unreachable due to broken link, unless you know where to find it) http://preview.machinekit.io/docs/documenting/updating-your-fork/ (also have a look here https://github.com/machinekit/machinekit-docs/blob/master/machinekit-documentation/documenting/updating-your-fork.asciidoc for non-broken image links)

1) If a user recognizes that a need exists, how does he/she communicate the need to the community?  I think this needs to be an issue.  But where?  In the main machinekit issue db or the machinekit-docs issue db? 

To me, it does’t matter. I’d prefer the machinekit-docs but if one is wrong, We can always correct that. Important to me is “catching the fly”

2) How does the user know if the issue has already been reported?  I guess the user should be directed to search the db.  Or maybe the docs should contain an autogenerated summary of open documentation issues with links.

http://preview.machinekit.io/docs/getting-help/#start-investigating (see points 6,7,8 and 9) explains a bit. Not looking at the structure now, do you think this type of info is good enough?

I think this page gets a “shell shock” effect though. We probably should break this in smaller pieces, with a diagram :)

3) If the user finds an open issue, how does he/she know if someone is working on this?  Are we going to take advantage of the 'Assignee' field in the github issue tracker?  I don't think this will work.  I think it only refers to members of the Machinekit organization.  So the user would read the comments and determine if someone is working on the issue and has started a fork.

yes, that’s how I see it. I guess he/she doesn’t other than asking at the issue itself. I also think assignees doesn’t work.

But how I see it is not the only thing important. It’s how we all see it, and what actually works is the most important.

4) How does the user find preliminary (WIP) documentation?  I guess this is like #3.  The user reads the comments looking for a link to a fork where work is being done.  Better yet, the person working on the documentation has done PR marked with something like "WIP-DO NOT MERGE" so that the preview is generated but not merged. 

yes, could be

Here a proposal for a process. What do you think?

0) Random user reads documentation, sees deficiency, searches issue db, and realizes deficiency is real.

yes

1) Random user (me), creates an Issue to flag need for a 'how to contribute to the documentation' document.

yes

2) Someone in Machinekit community becomes the Assignee.  This doesn't mean they'll write the docs, just that they'll curate the issue and see that it eventually gets resolved.

Curation means making sure it has an appropriate subject line and links to relevant forks.  Curation also means speaking up if it appears the issue has gone stale.

you’re proposing a consigliere type of role, so like giving tips, encouraging discussion, getting all noses pointing the same way, mental support. I think this comes close (but is not) to this: http://preview.machinekit.io/community/maintainers/

3) Random user forks and edits.  Random user is (strongly) encouraged to do WIP pull-requests early and often to allow previews to be generated.

yes, and I would even prefer if we could find a way to minimise WIP on private forks. My take: if it does not degenerate the documentation (we need a certain (i dont know what) quality), then unfinished work in the mainline will make collaboration easier.

4) Random user eventually submits actual PR to close issue.

yes

I think this is mostly the way we do it now, except for your point (2)

Let’s keep that thought.

Thanks,

Bas

[Bas de Bruijn]

> On 09 May 2016, at 15:26, Daniel Skrlin <d...@pmcstone.com> wrote:
>
> Correct me of I am wrong but if you are going to start anywhere shouldn't you be checking the LCNC docs first? I mean MK is the cherry on top of LCNC meaning if you get your set up/config working in LCNC all you are doing with MK is getting the remote capabilities. Sorry just my 2 cents.

I don’t think that’s all true, Another difference are the running on different platforms, and (in the pipeline) multicore support, instantiatiable components.

> But to be honest the docs are good. You just have to read them and apply them. Sorry if it's not cut and dry.

thx
Bas

[Bas de Bruijn]

Hi List

On 09 May 2016, at 15:58, Bas de Bruijn <b...@basdebruijn.com> wrote:

Since the 'fork and pull-request' model might be new to some potential contributors, I think the documentation should include a "How to contribute to the docs" document.  As I was thinking about that, I said to myself, "OK, smartass,  why don't you get off your butt and write one?"  Faced with such a compelling argument, I tried... and got stuck.  

I know where to find this one. One reason I’d like to get the diagram functionality (sequence editor, and whatnot) to run is to be able to make a diagram, which says more than words. http://asciidoctor.org/docs/asciidoctor-diagram/#specifying-diagram-generator-paths

Michael and me made some leaps yesterday evening and this morning:

We can now have different beautiful diagrams. Which say more than 1000 words !

result: http://preview.machinekit.io/docs/documenting/diagramtest/

source: https://github.com/mhaberler/machinekit-docs/blob/work/docs/documenting/diagramtest.ad

[WZ9V]

I was checking out the newbie getting started docs and ran into 404 errors on these links.

Installation options:

1. Use a pre-made image for Beaglebone Black

2. Install precompiled debian packages for amd64, i386, and arm7 (or later) systems like the Beaglebone Raspberry Pi2. This means configuring Apt, installing kernels and installing the runtime packages.
   
   

[WZ9V]

Above message applies to this link http://preview.machinekit.io/docs/index-getting-started/

[Bas de Bruijn]

> On 10 May 2016, at 22:43, WZ9V <dfrue...@gmail.com> wrote:
>
> I was checking out the newbie getting started docs and ran into 404 errors on these links.

Yeah, this is just a first cut. Links need to be checked and fixed, these aren't the only ones.

But that's "just work". Important is if this lowers barriers and makes for better readability.

If you're interested then have a look at the Machinekit-docs until all is better. All info is there too.

Cheers,
Bas