[erlang-questions] Erlang documentation -- a modest proposal

Lloyd R. Prentice <>
Thu Sep 22 23:56:30 CEST 2016


Hello,

To date, this thread has generated quite a few worthwhile insights and ideas. My fear is that they will be deep-sixed into the archive. On the other hand, major revision is a daunting task and unlikely to happen.

But maybe we can focus on specific issues and make iterative headway. 

Fewer than half of the functions in the lists library, for instance, have code examples. Suppose over the span of one week we were collectively focus on generating at least two code examples for each function in one library.

At the end of the week we could organize the submissions and vote on best candidates for inclusion in the docs. That done, we can pick another module.

Thus, with not much effort from any one individual, a small posse of volunteer Erlang wizards could make short work of deficiencies in the docs. 

Anyway, it's an idea.

All the best,

LRP

Sent from my iPad

> On Sep 21, 2016, at 6:52 AM, Roger Lipscombe <> wrote:
> 
>> On 21 September 2016 at 02:12, Richard A. O'Keefe <> wrote:
>> 
>>> On 20/09/16 8:20 PM, Roger Lipscombe wrote:
>>> 
>>> I *do* wish that -- somehow -- the docs could be marked up so that a
>>> Google search would jump directly to the appropriate function.
>> 
>> 
>> Can you point us to documentation for some other project
>> where this works?
> 
> I don't know if it *can* be made to work. I pointed to an example
> where, for some pages, Google returns links to headings on the page.
> It turns out that this is explained in this Google blog post:
> https://googleblog.blogspot.co.uk/2009/09/jump-to-information-you-want-right-from.html
> 
> That seems to suggest that it's fairly basic -- that is: it lists
> likely-looking headings from the page, and not necessarily the ones
> you care about. I was kinda hoping that with some extra tags on the
> headings, Google might recognise which sections were actually relevant
> to the user's search and provide quick links to those.
> 
> Regards,
> Roger.
> _______________________________________________
> erlang-questions mailing list
> 
> http://erlang.org/mailman/listinfo/erlang-questions



More information about the erlang-questions mailing list