Growing the docs about elixir-lang.github.com

[alco]

I mentioned four documentation categories in the beginning. The fourth one is not something that we can plan for, but could be a nice addition. It is currently represented by the Articles page on the wiki.

What I thought might be useful is to pick selected articles and embed them into the main site (as a kind of best practices guide). If it's a blog post, for example, we could ask the author to perhaps reformat it a bit to become a part of the main site's documentation. The blog post will still remain as a separate entity and the article may even link to it for attribution purposes.

Currently, the wiki page is fine for the purposes of referencing existing articles. We may simply continue going with that and dismiss the whole idea of adding Articles to the main site.

[josevalim]

I am not sure I undertand the purpose of technical guides. If the language reference is going to contain the current Getting Started guide plus more advanced topics on protocols and macros, it covers pretty much everything there is to talk about (at least until the current point). You mention:

Technical Guide which will go over all there is to know about macros, quoting and all their options and implications

I believe quoting and all their options, for example, needs to be part of the language reference for quote. The language reference should go into conceptual things like: what is a value and what is an ast in Elixir and how this implies on when to use Macro.escape_value, Macro.escape_quote and other utilities on the Macro module.

I agree completely with everything else. :) For now, I also agree we should leave the articles in the wiki since there are other important things to tackle!

[alco]

I am not sure I undertand the purpose of technical guides. If the language reference is going to contain the current Getting Started guide plus more advanced topics on protocols and macros, it covers pretty much everything there is to talk about (at least until the current point).

In a few words:

• Language Guide (getting started + advanced topics) will show how things are used.
• Technical guide will describe in detail how things work.
• Reference -- this is just the docs like we have now. Those describe individual modules/functions. There may simply not be a place for an in-depth guide in a docstring.

There is some overlap between those, but I wanted to separate them by intent. Because in real life there are users who simply want to get things done. Those will benefit the most from the Language guide and occasionally the Reference. There are also those who like to know how things work. Those will benefit the most from reading the Technical guide and the source code.

Technical Guide which will go over all there is to know about macros, quoting and all their options and implications

I believe quoting and all their options, for example, needs to be part of the language reference for quote.

Agree with you here. Listing all options of quote was not the best example. But showing an example of putting every option to work in a real-world context might not fit in the reference. This could make an article in the Technical guide.

[josevalim]

Perfect. So for now we should continue focusing on the Language Guide and Reference, the Technical Guide is something to worry about in the longer term, is that correct?

[alco]

That is correct.

[alco]

I've moved the description to a wiki page. Since this is a long-term goal, I'm closing the issue for now.