Re: [akka-user] Sharing my attempt at contributing to Akka

[Omer van Kloeten]

Sorry for not replying, I was not getting notifications for replies to my 
post for some reason.

Patrick, I think that's a great idea. I love how you're also adding the 
ability to run the code in-place, including all of the imports et al, since 
the current system sends me to look for what needs to be imported myself 
(and when it comes to implicits, that's a terrible bit of experience).

Thank you both for taking the time to reply!

Omer

On Saturday, September 3, 2016 at 9:40:47 AM UTC+3, rkuhn wrote:
>
> Ah, nice, I was not keeping up it seems! If we control the whole thing 
> then it should actually be possible to add the second kind of link as well 
> (directly to the snippet’s source).
>
> Regards,
>
> Roland
>
> 3 sep. 2016 kl. 08:30 skrev Patrik Nordwall  >:
>
> 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 . 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 
>  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  > 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 
>> 
>>  
>> 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

Re: [akka-user] Sharing my attempt at contributing to Akka

[Roland Kuhn]

Ah, nice, I was not keeping up it seems! If we control the whole thing then it 
should actually be possible to add the second kind of link as well (directly to 
the snippet’s source).

Regards,

Roland

> 3 sep. 2016 kl. 08:30 skrev Patrik Nordwall :
> 
> 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 . 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 
>  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  > 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 
> 
>  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 
> >> 

Re: [akka-user] Sharing my attempt at contributing to Akka

[Patrik Nordwall]

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 . 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
 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
> 
> 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

Re: [akka-user] Sharing my attempt at contributing to Akka

[Roland Kuhn]

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
 

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
 

 (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 :
> 
> 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 
> 
>  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 noth

[akka-user] Sharing my attempt at contributing to Akka

[Omer van Kloeten]

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 

 
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.