First paragraph of documentation style

[Peter Minten]

Hi all,

I'd like to ask if we can achieve a consensus on a point related to
documentation. In order to easily generate a summary for documentation
it would be best if the first paragraph of a @moduledoc, @typedoc or
@doc is a short one line description of the item being described.

With regard to writing style it's best to avoid "This module ...",
"Contains ..." or "This function ..." in favour of a more active style.
For example:

@moduledoc """
Convenience utilities for working with macros.

...
"""

@doc """
Expand an AST node until it no longer represents a macro.

Check expand_once/2 for more information on how expansion works and
expand_all/2 for recursive expansion.
"""

Currently the docs contain various writing/doc styles. Cleaning this up
would be a huge chore but it's easy to do and can be done in small bits
so it's something we could advertise as a good first step for someone
who wants to start contributing but doesn't feel confident to tackle the
more complicated topics.

Greetings,

Peter

[José Valim]

I agree Peter.

I am also copying John Warwick who has worked actively on the docs for his opinion.

Once everyone agrees on it, can you please send a pull request to the CONTRIBUTING.md guide adding a "## Contributing docs" section with your observations? Let's make it a standard. :)

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Lead Developer

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-core+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[John Warwick]

I think having a style guide for the docs is great. Just looked at the update to CONTRIBUTING and think it captures the idea.

Also agree with Peter's view that cleaning up the existing docs is a great way for a new developer to get exposure to the language.

thanks,

john

To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

[Chris Keele]

I'd enjoy the tour of the source that cleaning up the documentation would entail.

[Chris Keele]

I've worked my way A-E in my free time today (Access, Behaviour, Bitwise, Code, Dict, Enum, Exception) and it's been rewarding. I'm getting acquainted with the standard library, of course, but I'm also reading through a lot of great discussion on pull requests and elixir-lang-core, and getting a feel for Elixir style as-she-is-wrote.

These are my notes I took as I went along to try and develop a consistent documentation style. They are probably too formal to be put in CONTRIBUTING.md without scaring off potential contributors. However, if you'll advise me on them, I'd love to use them as a reference as I go through all of the docs in a consistency-refactor.

[Peter Minten]

On 08/28/2013 04:43 AM, Chris Keele wrote:
> I've worked my way A-E in my free time today (Access, Behaviour, Bitwise,
> Code, Dict, Enum, Exception) and it's been rewarding. I'm getting
> acquainted with the standard library, of course, but I'm also reading
> through a lot of great discussion on pull requests and elixir-lang-core,
> and getting a feel for Elixir style as-she-is-wrote.

Awesome. Thank you for picking this up.

> These are my notes <https://gist.github.com/christhekeele/6361477> I took

> as I went along to try and develop a consistent documentation style. They
> are probably too formal to be put in CONTRIBUTING.md without scaring off
> potential contributors. However, if you'll advise me on them, I'd love to
> use them as a reference as I go through all of the docs in a
> consistency-refactor.

Unfortunately it seems there's a problem with that gist, I can't open it.

Greetings,

Peter

[John Warwick]

Thanks Chris! I think we could have a separate documentation style guide and reference it from the CONTRIBUTING.md.

thanks,

john

[Chris Keele]

Fixed link: https://gist.github.com/christhekeele/6361519

[Peter Minten]

This looks great to me. We'll have to think about what the best place is to put such style info.

Chris Keele <d...@chriskeele.com>schreef:

[Chris Keele]

We could extend the elixir-lang/elixir wiki with a page similar to this one, broken down into Code, Docs, and Tests. Alternatively, we could have a STYLEGUIDE.md in the codebase for more project-specific conventions.

[Peter Minten]

I'm also working on Effective Elixir, which is somewhat of style guide
(in the spirit of Effective Go) for Elixir. See
https://github.com/pminten/effective_elixir

Mind you, that's not at all an official Elixir thing at the moment (I
expect much discussion about it as I try to give as clear guidelines as
possible, which inevitably will conflict with someone's coding style).

On 08/28/2013 11:13 PM, Chris Keele wrote:
> We could extend the elixir-lang/elixir wiki with a page similar to this one<https://github.com/alco/elixir/wiki/Contribution-Guidelines#coding-style>,

> broken down into Code, Docs, and Tests. Alternatively, we could have a
> STYLEGUIDE.md in the codebase for more project-specific conventions.
>
> On Wednesday, August 28, 2013 11:59:51 AM UTC-5, Peter Minten wrote:
>>
>> This looks great to me. We'll have to think about what the best place is
>> to put such style info.
>>

>> Chris Keele <d...@chriskeele.com <javascript:>>schreef:

>>
>> Fixed link: https://gist.github.com/christhekeele/6361519
>>
>> On Wednesday, August 28, 2013 7:55:34 AM UTC-5, John Warwick wrote:
>>>
>>> Thanks Chris! I think we could have a separate documentation style guide
>>> and reference it from the CONTRIBUTING.md.
>>>
>>> thanks,
>>> john
>>>
>>>
>>> On Tuesday, August 27, 2013 10:43:39 PM UTC-4, Chris Keele wrote:
>>>>
>>>> I've worked my way A-E in my free time today (Access, Behaviour,
>>>> Bitwise, Code, Dict, Enum, Exception) and it's been rewarding. I'm getting
>>>> acquainted with the standard library, of course, but I'm also reading
>>>> through a lot of great discussion on pull requests and elixir-lang-core,
>>>> and getting a feel for Elixir style as-she-is-wrote.
>>>>

>>>> These are my notes <https://gist.github.com/christhekeele/6361477> I

>>>> took as I went along to try and develop a consistent documentation style.
>>>> They are probably too formal to be put in CONTRIBUTING.md without scaring
>>>> off potential contributors. However, if you'll advise me on them, I'd love
>>>> to use them as a reference as I go through all of the docs in a
>>>> consistency-refactor.
>>>>
>>>>
>>>> --
>> You received this message because you are subscribed to the Google Groups
>> "elixir-lang-core" group.
>> To unsubscribe from this group and stop receiving emails from it, send an

>> email to elixir-lang-co...@googlegroups.com <javascript:>.

[Chris Keele]

Wanted to note I haven't dropped the ball on this, I got about 1/3rd of the way through core in a week. Then I noticed enough churn when rebasing off master, and discussion of major refactors (like cleaning up Kernel), to decide to put it on hold for a while.

Given the clip I was going at, and the directions core is moving in, I think I'd be able to fit it into my free time and churn it out in about 2-3 weeks. When we get a 1.0.dev, I hope to be able to tackle it before we cycle through alpha, beta, rc, or whatever, to release.

It'll look great with the new ExDoc function summary view!

In the meantime I'll probably use my thoughts from that first 1/3rd to put together a pull request with some tenative guidelines, summarizing this thread, so other people can pick up Mix, ExUnit, etc around the same time.

[Chris Keele]

NVM, a perfect summary made it into CONTRIBUTING.md sometime when I looked away from master.