Add Getting Started section to the README

[mkrull]

As someone new to Perl 6 I found some documentation missing and in the processes of getting familiar with certain undocumented or poorly documented packages it seems natural for me to contribute docs. Especially from the unspoiled 'what would a new user need' perspective.

But even though I am not new to programming, not new to documenting code or writing docs in general and not even new to writing POD I am having a hard time to figure out where to actually start contributing.

I am pretty sure a quick getting started guide could help a great deal to get drive-by contributions to the docs.

[pmichaud]

How should the getting started guide proposed here differ from http://perl6.org/getting-started/ ?

Or, put another way, is http://perl6.org/getting-started/ a good start on this, or is it missing something fundamental (and if so, what)?

[mkrull]

I was thinking more of a getting started guide for this repo. A quick pointer to how documentation works to make it easier to contribute pieces of documentation quickly and still correctly.

Because it looks like a code repo and it is difficult for me to seperate code and content.

[uvtc]

The readme here already has a "Help Wanted!" section. In that section should be a link to the new CONTRIBUTING.md doc. That CONTRIBUTING.md doc is still quite new I think --- maybe it should contain additional info such as how often the docs are pulled from this repo, processed, and uploaded to doc.perl6.org.

[paultcochrane]

Any help is greatly appreciated. Thanks for your interest!

Moritz has been the driving force behind the documentation effort, so it's probably a good idea to ask him for tips about where to begin. In general, you can simply ping someone on the #perl6 channel on freenode.net and you'll get pointed in the right direction.

Things which occur to me right now which could be done include:

• clone the repo and grep/ack for TODO items in the POD; the POD is under the lib directory (and subdirs). If you find something which you think you could document, write it up and add it as a PR. Make sure to also cross-check with the perl6/specs repo to see if there is some information about that topic there already which could be massaged for good use in per6/doc.
• simply read the docs. :-) If you find anything which you don't understand, or doesn't seem clear, or could be added, or typos, or whatever, make the relevant change(s) and submit a PR. Enough good PRs and you'll get a commit bit and you can really let loose ;-)
• check the current docs for examples and anywhere you think that a concept would be better explained through an example, add the code and submit a PR
• to build the documentation locally you'll need to install Pod::To::HTML via panda and then run the htmlify.p6 script in the perl6/doc base directory.
• some internal links don't always work, or might not be linked to the correct document. Again, correct the POD and submit a PR.
• note also the CONTRIBUTING.md doc which was added to the repo either this morning or late last night; this document describes the basic standards which should be used when creating documentation. If you find some docs which don't meet the standards, again, change the text and submit a PR :-)
• Mortiz' Perl 5 to Perl 6 introduction blog posts need to be merged into the 5to6.pod document in perl6/doc. It's important that both the how and the why of the changes between Perl 5 and Perl 6, which are documented in Moritz' blog posts, are maintained in the 5to6.pod document in perl6/doc. That might be a good place to start.

As you can see, there is a lot to do, but please don't be daunted by it! We need a new user's perspective when looking at the documentation, and any fresh eyes looking over the docs is most certainly welcome!

Hope that helped a bit!

[mkrull]

That certainly helped and is close to what I was thinking of. To make it easy for new users to contribute documentation a lot of projects set up some "my first contribution" guide much like the Symphony or puppet guides.

I understand that those probably have more resources at their disposal but still.. people are lazy.. I am most certainly lazy and if it is as much of a hurdle to contribute to the docs as it is to find out about a class or type or package by reading the tests or source in the first place I and probably others will fail to do it.

It might even only seem to be a hurdle because I as the possible contributor have no idea where to start. It is important to provide that easy starter because everybody could write docs but only people familiar with the process can write the howto guide.

[moritz]

Considering the current state of https://github.com/perl6/doc/#help-wanted and the documents linked from there, is there something left to do for this ticket?

[mkrull]

Basically that would be a step by step example of how to contribute correctly.

From the potential contributors perspective: I want to contribute to the IO::Socket docs. So how do I do it? I could figure it out myself but it will take some time.. so I leave. What should be there so I don't?

A guide from checkout to accepted pull request would be the best way to keep it as simple as possible.

Something like: fork, run this generator for a template, edit, commit, create pull request.
Also: What kind of packages am supposed to document? Is there a difference between contributing docs of a third party package/module and a standard library?

[raiph]

Fwiw here's what I've done in the past:

1. Use the web to read doc.perl6.org.
2. Find something I want to improve.
3. Optionally discuss it on #perl6 and/or with Moritz.
4. Follow links to the matching github repo file.
5. Use regular github web interface to do the rest
   (click Pencil, edit, summarize commit, save, submit PR)

(IWBNI if p6doc pages could attempt to link to the
corresponding github file to make step 4 easier.)

Perhaps this is problematic for reasons I'm not
aware of, but if not, then maybe this could be a
leading easy on-ramp.

raiph

On Wed, Feb 25, 2015 at 3:45 PM, Matthias Krull [email protected]
wrote:

Basically that would be a step by step example of how to contribute
correctly.

From the potential contributors perspective: I want to contribute to the
IO::Socket docs. So how do I do it? I could figure it out myself but it
will take some time.. so I leave. What should be there so I don't?

A guide from checkout to accepted pull request would be the best way to
keep it as simple as possible.

Something like: fork, run this generator for a template, edit, commit,
create pull request.
Also: What kind of packages am supposed to document? Is there a difference
between contributing docs of a third party package/module and a standard
library?

—
Reply to this email directly or view it on GitHub
#53 (comment).

raiph

[mkrull]

The comments here are a good starter and commit bb20897 helped a great deal in understanding how the documentation works and how to get it running localy step by step. I will close the issue and get on irc for questions that arise and add to the document where I have difficulties that get resolved.

[FROGGS]

+1

Am 25.02.2015 um 23:47 schrieb raiph:

Fwiw here's what I've done in the past:

1. Use the web to read doc.perl6.org.
2. Find something I want to improve.
3. Optionally discuss it on #perl6 and/or with Moritz.
4. Follow links to the matching github repo file.
5. Use regular github web interface to do the rest
   (click Pencil, edit, summarize commit, save, submit PR)

(IWBNI if p6doc pages could attempt to link to the
corresponding github file to make step 4 easier.)

Perhaps this is problematic for reasons I'm not
aware of, but if not, then maybe this could be a
leading easy on-ramp.

raiph

On Wed, Feb 25, 2015 at 3:45 PM, Matthias Krull [email protected]
wrote:

Basically that would be a step by step example of how to contribute
correctly.

From the potential contributors perspective: I want to contribute to the
IO::Socket docs. So how do I do it? I could figure it out myself but it
will take some time.. so I leave. What should be there so I don't?

A guide from checkout to accepted pull request would be the best way to
keep it as simple as possible.

Something like: fork, run this generator for a template, edit, commit,
create pull request.
Also: What kind of packages am supposed to document? Is there a
difference
between contributing docs of a third party package/module and a standard
library?

—
Reply to this email directly or view it on GitHub
#53 (comment).

raiph

—
Reply to this email directly or view it on GitHub
#53 (comment).

[paultcochrane]

(IWBNI if p6doc pages could attempt to link to the corresponding github file to make step 4 easier.)

Initial implementation as of 5b89eac. Comments, improvements, etc. most welcome.

[moritz]

@paultcochrane IMHO it would be more useful to link to the non-raw pages on github (https://github.com/perl6/doc/blob/master/lib/Language/classtut.pod instead of https://raw.githubusercontent.com/perl6/doc/master/lib/Language/classtut.pod). Then the edit link/icon is just a click away.

[paultcochrane]

To be honest, I think so too. However, I wanted to avoid the case where github can't dispaly the pod, which happened often enough that I implemented it the way I did. Maybe a link to both?

[coke]

Do we have an example of where github isn't displaying the pod properly?

[raiph]

@coke Am I right that the docs are now tested after commits are made so that broken Pod gets fixed near enough immediately? (If so, then, to the degree github's renderer tracks the one used to test commits, there presumably won't be any examples.)