Great points John! It sounds like we should at least have a "walk-through" page with how a new user can submit a PR for the docs. Ideally, this could be linked from the various intermediate pages you hit when trying to "Edit this page", but I'm not sure if that's possible.
On 7/31/2016 5:59 PM, John Kasunich wrote: > > > 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. > > > -- Charles Steinkuehler [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.
