Hi Omer, thanks for writing this up instead of just walking away!
Most of what you describe is already there, apart from some links. One of those link would probably be simple to add, the other I’m not so sure about: You can edit files on github, which will create a fork behind the scenes from which you can open a PR, which in turn will trigger PR validation etc. The link to the editor for the file you mention would be https://github.com/akka/akka/edit/master/akka-docs/rst/scala/http/routing-dsl/directives/custom-directives.rst <https://github.com/akka/akka/edit/master/akka-docs/rst/scala/http/routing-dsl/directives/custom-directives.rst> Since you want to edit code, you’d have to know where that snippet in the documentation page is coming from, and since it is taken from actual test code which is organized like code (and not like text) that is not so straight forward. In the editor that opens for the link above you can see where to go, though, e.g. for the first snippet it would be https://github.com/akka/akka/edit/master/akka-docs/rst/scala/http/routing-dsl/directives/../../../code/docs/http/scaladsl/server/directives/CustomDirectivesExamplesSpec.scala <https://github.com/akka/akka/edit/master/akka-docs/rst/scala/code/docs/http/scaladsl/server/directives/CustomDirectivesExamplesSpec.scala> (which github will then canonicalize itself) For extremely simple edits, and where only a single file is affected, this can be used effectively—but only if you know what you are doing. The problem is that PR validation takes a long time since everything is compiled and tested and the codebase is huge by now. And if PR validation fails you will wish that you have checked out the code on your local computer so that you experiment with a much quicker turnaround time. Now, github is for sure not the optimal tool for editing. It would probably be possible to create an online IDE for this kind of work that smoothly integrates with the docs. But do you think that developing that would be time well spent by the Akka team? Have you seen such a solution deployed by any other project, anywhere? If it exists, it would be great to see whether it can be reused! Coming back to concrete first steps: in your opinion, would it be worth it to add the first kind of link (that points to the documentation text source) to the generated documentation pages? Or would it be better to add a description to CONTRIBUTING.md? Or both? Regards, Roland > 3 sep. 2016 kl. 00:23 skrev Omer van Kloeten <omer.van.kloe...@gmail.com>: > > Hi all, > > First off, let me thank everyone here for their time and energy spent making > Akka the amazing toolset it is today. > > Following the Akka developer survey I answered today, I realized I wanted to > contribute to Akka and decided to just do it. Since I'm too much of a novice > in the details of Akka to solve any open issues and have not had enough > experience contributing to large open-source projects in the past, I decided > to start off small and contribute documentation. > My idea was to contribute more code samples to the Custom Directives > <http://doc.akka.io/docs/akka/2.4.9/scala/http/routing-dsl/directives/custom-directives.html> > page of akka-http to make modifiers more easy to understand. > > The friction involved in the process of contributing made me abandon my > attempt. I'd like to share my experience: > > I decided which three lines of code I wanted to contribute. Then I went into > the doc page itself and looked for a "contribute" / "edit" / etc. button or > the well known "fork me on github" button. None exists. Huh. > As an aside, I knew the docs were on GitHub (basing this on a conversation I > had with Konrad back in Scala Days Berlin) but found no indicator that this > was the case on the page itself. > > I went to Akka's GitHub repo and found CONTRIBUTING.MD. I was greeted by a > huge wall of text. I searched for "doc" and found the part talking about > documentation contribution (I guess?) with a list of requirements and no > examples or references (and a confusing last two paragraphs). The references > that did exist were to tools: RST and Sphinx. Not sure about whether I need > to learn either. I'm great with Markdown, does that help? Also I need to > start writing tests for my three lines of code? > > OK let's try to move forward - contributing can't be that hard. Next I > decided to just see where the actual docs existed so I searched the repo for > "Custom Directives" which raised too many results and then "Configuration > Labeling" (a subheader) which showed two results for docs, one for Scala and > one for Java. I have to write my sample code in both? this wasn't mentioned > anywhere. > Reading the source of the file (custom-directives.rst) made me realize > samples were imported from external files. Where do I put mine? > > I forked the repo, looked at my clock, realized 20 minutes have already > passed and that I have achieved almost nothing and decided I didn't have any > more time for this. > > I'm sure you can empathize with my frustration, since all I wanted to do was > contribute three lines of code that would have made great strides towards > explaining something to a new user coming across the official docs. I know I > would have been super happy to see them when I first met that page. > > Now I realize things are complicated - you want to verify all code, maintain > standards and so on, and I applaud your work - but we have to find a better > way to do it. > > My dream docs contribution process? An in-place editor (wiki-style) where > after I add / change code, I wait for the code to compile (online) and my > tests to run (in a sandbox, of cource) and if they all do, it gets sent to a > moderator for approval (opens a pull request behind the scenes?). If only > text changed, it just opens that pull request. > > I'll probably try contributing the samples anyway, but I'll wait until I have > maybe an hour or two to spend on it. > > HTH, > Omer > > -- > >>>>>>>>>> Read the docs: http://akka.io/docs/ <http://akka.io/docs/> > >>>>>>>>>> Check the FAQ: > >>>>>>>>>> http://doc.akka.io/docs/akka/current/additional/faq.html > >>>>>>>>>> <http://doc.akka.io/docs/akka/current/additional/faq.html> > >>>>>>>>>> Search the archives: https://groups.google.com/group/akka-user > >>>>>>>>>> <https://groups.google.com/group/akka-user> > --- > You received this message because you are subscribed to the Google Groups > "Akka User List" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to akka-user+unsubscr...@googlegroups.com > <mailto:akka-user+unsubscr...@googlegroups.com>. > To post to this group, send email to akka-user@googlegroups.com > <mailto:akka-user@googlegroups.com>. > Visit this group at https://groups.google.com/group/akka-user > <https://groups.google.com/group/akka-user>. > For more options, visit https://groups.google.com/d/optout > <https://groups.google.com/d/optout>. -- >>>>>>>>>> Read the docs: http://akka.io/docs/ >>>>>>>>>> Check the FAQ: >>>>>>>>>> http://doc.akka.io/docs/akka/current/additional/faq.html >>>>>>>>>> Search the archives: https://groups.google.com/group/akka-user --- You received this message because you are subscribed to the Google Groups "Akka User List" group. To unsubscribe from this group and stop receiving emails from it, send an email to akka-user+unsubscr...@googlegroups.com. To post to this group, send email to akka-user@googlegroups.com. Visit this group at https://groups.google.com/group/akka-user. For more options, visit https://groups.google.com/d/optout.
