On Mon, May 30, 2016, at 07:49 AM, Bas de Bruijn wrote: > Dear list, > > Last few weeks, Michael, Mick and me have been working on getting the website > and documentation tools and flows into better shape. We have tried to make > reading, searching, and contributing to the documentation as easy as possible. > > The highlights: > > - There’s 1 place to read: machinekit.io/docs <http://machinekit.io/docs> > This holds all the documentation we have > - 2 click editing of content. A wiki like experience, without the downside of > a wiki. > http://www.machinekit.io/docs/documenting/contributing-documentation/#2-click-editing-with-edit-me-button > > <http://www.machinekit.io/docs/documenting/contributing-documentation/#2-click-editing-with-edit-me-button>
Exactly what is the downside of a wiki? Clicking the "edit me" button does not let me edit the page. It expects me to log into (and thus to have) a github account. Github might not be an obstacle to developers, but it is to users. You say you want users to contribute to the documentation, so please make it easy to do so. > We have tried to lower the barrier as much as we could. > We specifically did not focus on content and structure yet, just > getting eveything together into a single format, git backed, > automatically served, and easy to edit. I understand. You have nice shiny new infrastructure. Unfortunately, you have the same content. Still missing lots of stuff. Still out of date. > There’s still tons of work to do on the documentation, and > we can’t do it all on our own. > Therefor we would like to ask _you_ to: Who is "you" in the above sentence? Users of Machinekit? Or the other developers who have contributed to Machinekit? There are time when users can make valuable contributions to documentation. But most of the time, when someone writes new code, the ONLY person who can document it is the one who wrote it, because he is the only one who knows what problem it is trying to solve, how it solves the problem, and what its requirements and limitation are. > - Read through this short overview first: > http://www.machinekit.io/docs/site/about-this-site/index.html > <http://www.machinekit.io/docs/site/about-this-site/index.html> > - Read through the docs and submit edits where you think the docs are wrong > or incomplete > - Submit any new material you feel is currently missing through the SandBox > section http://www.machinekit.io/docs/sandbox/index.html > <http://www.machinekit.io/docs/sandbox/index.html> > - Raise any issues through the specific tracker issues listed in > http://www.machinekit.io/docs/site/about-this-site/#discussing-improvements-use-the-a-href-https-github-com-machinekit-machinekit-docs-issues-docs-tracker-a > > <http://www.machinekit.io/docs/site/about-this-site/#discussing-improvements-use-the-a-href-https-github-com-machinekit-machinekit-docs-issues-docs-tracker-a> > - Help improve documentation! I would like to contribute. So I'm going to walk you through the process as I am experiencing it right now. The last time I tried using Machinekit was in February. I had much the same frustrations with documentation back then, and I did create a github account at that time. One obstacle overcome - normal users won't be so lucky. So this time (after trying to remember the password) I was able to log in. Now I'm on this page: https://github.com/machinekit/machinekit-docs//edit/master/docs/documenting/contributing-documentation.asciidoc In big letters it says: You need to fork this repository to propose changes. Sorry, you’re not able to edit this repository directly— you need to fork it and propose your changes from there instead. As a user, I have no idea what a "repository" is and a fork is for eating. So I click on "learn more". It explains that forking makes a copy of a repository so I don't screw up the original. OK, makes sense. I still don't know what a repository is. Specifically, the question in my mind is - am I about to make a copy of the page I wanted to edit? or of the entire documentation tree? or of the entire project, source and all? Ignoring that question, I go back and click on Fork and propose changes. I edited the page (added a line pointing out that you need a github account, and the link to sign up). Then instead of the "save" that a user expects, I have to click on "propose changes". Am I done? Nope. I'm taken to yet another page, where I am shown a diff of my change and have to click yet another button to "create pull request". So I do. Am I done? Nope. Yet another page, more crap that I don't care about, and yet another "create pull request" button. So I click it. I get a page that shows some checks need to happen, and if I sit there for a while the yellow eventually turns green. There is a button at the bottom to close the pull request, but I don't know if that means "close" as in "finish", or as in "cancel". I have no idea how to get back to the page I was originally on when I clicked the "edit this page" button. (Other than by hitting "back" a bunch of times, or going back to the original link. I suppose I should have clicked "open in new tab" when I wanted to edit the page. Having made it back to the original page, I find that my edit isn't there... Git and github might be good for programmers who need to carefully control access to source code or master documents. Git and github are NOT friendly to a random user who wants to make a minor (or even not-so-minor) improvement to the documents. -- John Kasunich [email protected] -- 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 [email protected]. Visit this group at https://groups.google.com/group/machinekit. For more options, visit https://groups.google.com/d/optout.
