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

Lloyd R. Prentice lloyd@REDACTED
Mon Jun 2 20:43:56 CEST 2014


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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20140602/b094ee87/attachment.htm>


More information about the erlang-questions mailing list