Contributing Examples to the Documentation

[Oleg Grenrus]

On 05.01.2017 00:01, Ben Gamari wrote:
> Sunjay Varma <varma.sunjay at gmail.com> writes:
>
>> Hi,
>> I'm considering contributing examples to the documentation. I wanted to
>> start with something like Data.List because it is one of the modules I end
>> up using the most. I think a few examples for each function would help
>> users understand them better. I find myself referring back to books like
>> learn you a haskell because I don't remember exactly what I'm supposed to
>> do with a function.
>>
>> Doing one module seems like a good start and hopefully we can have some
>> other people begin to add their own examples too.
>>
>> Is this a worthwhile contribution? I haven't contributed before and so I
>> think it's prudent to ask before I add something no one wants.
>>
> This would be amazing! Many people have remarked that GHC's library
> documentation is in need of examples; we just need someone to step up
> and start contributing patches.
>
>> Are there any examples of modules with good code examples that I should use
>> as a reference? I want to include both the code and output of the example
>> as if the user was running ghci. Are there any guidelines for contributing
>> documentation?
>>
> I think Edward's lens library is probably a good example here. I know
> of few good examples in GHC itself.

And `lens` also uses `doctest` to actually verify the examples. Let's
keep in mind that GHC might want to doctest examples too at some point.
If any have ideas how that can happen (also having QuickCheck tests and
doctests would be great too), I can try to implement that.

>> When I say Data.List, I really mean Data.Foldable and Data.Traversable
>> since that is where the functions are actually implemented.
>>
> These are great places to start.
>
>> I noticed the GitHub repo said that Pull Requests were okay for easy to
>> review documentation changes. Can I open a pull request there or should I
>> follow another process?
>>
> We prefer to take patches on Phabricator. However, to lower the barrier
> to small patches like this I have suggested in the past that we accept
> GitHub pull requests for small changes.
>
>> Please let me know when you can. I don't have an exact timeline for when
>> this will be done, but hopefully I'll have something in the next few weeks.
>> I don't anticipate that it will take long once I sit down to do it.
>>
> Great. Let us know if you encounter friction.
>
>> I've always complained about a lack of examples and never done anything
>> about it. Hopefully I can practice what I preach and contribute some in
>> order to make the documentation a little better for everyone.
>>
>> Thanks for helping to make this language so great!
> And thanks to you for helping as well!
>
> Cheers,
>
> - Ben
>
>
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20170105/fe89f14b/attachment.sig>