Contributing Examples to the Documentation

[Ben Gamari]

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.

> 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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 487 bytes
Desc: not available
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20170104/7e367a68/attachment.sig>