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.
