Hi John, Thanks for the feedback, especially the part where you run thru the edit-me process.
> On 01 Aug 2016, at 00:59, John Kasunich <[email protected]> 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? The most important reasons why we didn’t use a wiki were: A wiki has little implicit structure. Personally I think structure is the most important thing that readers need (especially if you’re new). Wiki’s very fast become a mess and are hard to maintain (that has nothing to do with the current state of the docs btw :) ) And the most important reasons to use the repository and the jekyll build were: we can use C4 on the docs repository (which is social contract) diagrams and text are rendered and readable. Which was a huge complaint... readability. > > 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. yes that’s true. > >> 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. all who feel that they can and want to help out by fixing a typo, a link, an error or maybe write down how to set up something that they have done. I agree with your statement that the person writing code is also the one who should document. But we have what we have, and like you said. A lot of stuff is really out of date. > >> - 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”. This should be better explained in the instructions. Your PR has been built in preview.machinekit.io <http://preview.machinekit.io/> and you can view your change there. You can add more commits if you’re not satisfied. And a maintainer will merge the PR in the end. > > 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. good point. We should look if we can do this automatically from the button link > > 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. I understand your concern, and we need to look if we can improve the “2 click edit” explanation page, where there can be some more background about what to expect. Can you tell me what exactly is missing in the instructions? http://www.machinekit.io/docs/documenting/contributing-documentation/#2-click-editing-with-edit-this-page-link <http://www.machinekit.io/docs/documenting/contributing-documentation/#2-click-editing-with-edit-this-page-link> does it need more pictures? does it need more detailed explanation what’s happening like your example above? Something else? Bas > > -- > 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.
