[erlang-questions] Erlang docs was Re: How to return all records in dets

[lloyd@REDACTED]

Hi Garrett,
 
I'll try it.
 
I don't mind doing what I can to improve docs within the limits of my knowledge. It's the least I can do to pay back the tremendous effort that Erlang developers and contributors have invested to date.
 
All the best,
 
L.
 
 
-----Original Message-----
From: "Garrett Smith" <g@REDACTED>
Sent: Monday, June 2, 2014 3:14pm
To: "Lloyd R. Prentice" <lloyd@REDACTED>
Cc: "Jesper Louis Andersen" <jesper.louis.andersen@REDACTED>, "Erlang (E-mail)" <erlang-questions@REDACTED>
Subject: Re: [erlang-questions] Erlang docs was Re: How to return all records in dets



I'm still not clear why just updating the *existing* docs -- adding
examples, clarifying points of confusion, etc. isn't the obvious next
step here. So, you find something confusing, unclear, or wrong. After
getting help here, set aside some Saturday morning with and dive into
the docs source. When you like the result, send a pull request.

Maybe pick one of these lapses/gaps in the docs, based on this thread,
and just try this?

This, btw, is exactly why I never bring up "docs quality" -- ever --
in open source projects. The likelihood that someone will ask *me* to
help improve them is somewhere between 99.999% and 100% :)

On Mon, Jun 2, 2014 at 1:43 PM, Lloyd R. Prentice <lloyd@REDACTED> wrote:
> Hello,
>
> So many thoughtful ideas and comments regarding Erlang docs came out in the
> thread "How to return all records in dets," I'm taking the liberty of
> changing the subject line. As I find time over the next week I'll try to
> extract, summarize, and category the constructive contributions.
>
> Meanwhile, three thoughts occur to me:
>
> - Why does this topic matter? Because, speaking for myself, as good as they
> are, my inability to find answers that I needed at one time or another in
> Erlang docs has cost me countless wasted and frustrating hours. Integrate
> that experience across the past, current, and future Erlang community and
> how many hours are we talking about? If each of us did just a bit to work
> toward making the docs best-of-breed, how much time would we ultimately save
> individually and collectively?
>
> - The responses do suggest that the path toward improving docs will involve
> grappling with both technical and cultural/organizational/governance issues.
>
> - Within the past 12 hours I've unsuccessfully asked two questions of the
> docs: a) A look at the digraph library left me confused about how to query
> the graphs, in part out confusion over vertices and labels. This may just be
> a matter of me not reading carefully enough. b) A look at ordsets gave me no
> indication of resource costs of adopting ordsets as solution to my project
> (nor, best I can determine is this information readily available for other
> data structures.)
>
> These two examples suggest that work toward improving docs will require both
> noobies to point   out content lapses and confusing language and
> wizard/gurus to get the story straight.
>
> Best to all,
>
> Lloyd
>
> Sent from my iPad
>
> On Jun 2, 2014, at 11:15 AM, Jesper Louis Andersen
> <jesper.louis.andersen@REDACTED> wrote:
>
>
> On Mon, Jun 2, 2014 at 2:25 PM, Anthony Ramine <n.oxyde@REDACTED> wrote:
>>
>> OTP is a reasonably well-maintained Git repository. It is now using
>> GitHub’s pull requests, which makes it easy to contribute to, at least
>> according to the persons who wanted OTP to depend on GitHub.
>
>
> Also worth mentioning: We have "Users Guide" documentation exactly for the
> purpose of writing User Guides for various parts of the Erlang system. They
> are not references, but *guides* which tend to explain the back-story of how
> to use a given application.
>
> References are just that. Quick information for those in the know. Think
> FreeBSD/OpenBSD man pages in quality.
>
>
> --
> J.
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20140602/2b7d3a7c/attachment.htm>