<font face="arial" size="2"><p style="margin:0;padding:0;">Hi Garrett,</p>
<p style="margin:0;padding:0;"> </p>
<p style="margin:0;padding:0;">I'll try it.</p>
<p style="margin:0;padding:0;"> </p>
<p style="margin:0;padding:0;">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.</p>
<p style="margin:0;padding:0;"> </p>
<p style="margin:0;padding:0;">All the best,</p>
<p style="margin:0;padding:0;"> </p>
<p style="margin:0;padding:0;">L.</p>
<p style="margin:0;padding:0;"> </p>
<p style="margin:0;padding:0;"> </p>
<p style="margin:0;padding:0;">-----Original Message-----<br />From: "Garrett Smith" <g@rre.tt><br />Sent: Monday, June 2, 2014 3:14pm<br />To: "Lloyd R. Prentice" <lloyd@writersglen.com><br />Cc: "Jesper Louis Andersen" <jesper.louis.andersen@gmail.com>, "Erlang (E-mail)" <erlang-questions@erlang.org><br />Subject: Re: [erlang-questions] Erlang docs was Re: How to return all records in dets<br /><br /></p>
<div id="SafeStyles1401737697">
<p style="margin:0;padding:0;">I'm still not clear why just updating the *existing* docs -- adding<br />examples, clarifying points of confusion, etc. isn't the obvious next<br />step here. So, you find something confusing, unclear, or wrong. After<br />getting help here, set aside some Saturday morning with and dive into<br />the docs source. When you like the result, send a pull request.<br /><br />Maybe pick one of these lapses/gaps in the docs, based on this thread,<br />and just try this?<br /><br />This, btw, is exactly why I never bring up "docs quality" -- ever --<br />in open source projects. The likelihood that someone will ask *me* to<br />help improve them is somewhere between 99.999% and 100% :)<br /><br />On Mon, Jun 2, 2014 at 1:43 PM, Lloyd R. Prentice <lloyd@writersglen.com> wrote:<br />> Hello,<br />><br />> So many thoughtful ideas and comments regarding Erlang docs came out in the<br />> thread "How to return all records in dets," I'm taking the liberty of<br />> changing the subject line. As I find time over the next week I'll try to<br />> extract, summarize, and category the constructive contributions.<br />><br />> Meanwhile, three thoughts occur to me:<br />><br />> - Why does this topic matter? Because, speaking for myself, as good as they<br />> are, my inability to find answers that I needed at one time or another in<br />> Erlang docs has cost me countless wasted and frustrating hours. Integrate<br />> that experience across the past, current, and future Erlang community and<br />> how many hours are we talking about? If each of us did just a bit to work<br />> toward making the docs best-of-breed, how much time would we ultimately save<br />> individually and collectively?<br />><br />> - The responses do suggest that the path toward improving docs will involve<br />> grappling with both technical and cultural/organizational/governance issues.<br />><br />> - Within the past 12 hours I've unsuccessfully asked two questions of the<br />> docs: a) A look at the digraph library left me confused about how to query<br />> the graphs, in part out confusion over vertices and labels. This may just be<br />> a matter of me not reading carefully enough. b) A look at ordsets gave me no<br />> indication of resource costs of adopting ordsets as solution to my project<br />> (nor, best I can determine is this information readily available for other<br />> data structures.)<br />><br />> These two examples suggest that work toward improving docs will require both<br />> noobies to point   out content lapses and confusing language and<br />> wizard/gurus to get the story straight.<br />><br />> Best to all,<br />><br />> Lloyd<br />><br />> Sent from my iPad<br />><br />> On Jun 2, 2014, at 11:15 AM, Jesper Louis Andersen<br />> <jesper.louis.andersen@gmail.com> wrote:<br />><br />><br />> On Mon, Jun 2, 2014 at 2:25 PM, Anthony Ramine <n.oxyde@gmail.com> wrote:<br />>><br />>> OTP is a reasonably well-maintained Git repository. It is now using<br />>> GitHub’s pull requests, which makes it easy to contribute to, at least<br />>> according to the persons who wanted OTP to depend on GitHub.<br />><br />><br />> Also worth mentioning: We have "Users Guide" documentation exactly for the<br />> purpose of writing User Guides for various parts of the Erlang system. They<br />> are not references, but *guides* which tend to explain the back-story of how<br />> to use a given application.<br />><br />> References are just that. Quick information for those in the know. Think<br />> FreeBSD/OpenBSD man pages in quality.<br />><br />><br />> --<br />> J.<br />><br />> _______________________________________________<br />> erlang-questions mailing list<br />> erlang-questions@erlang.org<br />> http://erlang.org/mailman/listinfo/erlang-questions<br />><br />><br />> _______________________________________________<br />> erlang-questions mailing list<br />> erlang-questions@erlang.org<br />> http://erlang.org/mailman/listinfo/erlang-questions<br />></p>
</div></font>