Hi Omer, Thanks for very valuable feedback. Your email in itself is a great contribution. Thanks for taking the time to write it down. We need to improve here.
We will migrate all documentation to Markdown with some extensions and tooling called Paradox <https://github.com/lightbend/paradox>. After that we should write a short guide focused on how to contribute to the documentation. It's an excellent place to start for new contributors and we must remove the friction. First out is actually Akka Http. We will move it to a separate repository <https://github.com/akka/akka-meta/issues/27> and will migrate its documentation to Paradox in that process. It will not happen overnight, but we will work on it. Help from community with improving this and all other things in Akka is very much welcome. Cheers, Patrik On Sat, Sep 3, 2016 at 12:23 AM, Omer van Kloeten < omer.van.kloe...@gmail.com> wrote: > 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/ > >>>>>>>>>> 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. > -- Patrik Nordwall Akka Tech Lead Lightbend <http://www.lightbend.com/> - Reactive apps on the JVM Twitter: @patriknw -- >>>>>>>>>> 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.
