add explanation for each item about head

[tomlutzenberger]

Guys.... why not use the Wiki?
That's what it's made for 😉

[chrisbo]

IMO. One page, in order and well commented

[tomlutzenberger]

I think, there are 2 options.

• A Wiki (GitHub help section):

GitHub Wikis are a place in your repository where you can share long-form content about your project, such as how to use it, how it's been designed, manifestos on its core principles, and so on. Whereas a README is intended to quickly orient readers as to what your project can do, wikis can be used to provide additional documentation.

• GitHub Pages

Both options have some benefits:

1. Separated Documentation
2. Prevents "unnecessary" commits

IMHO: I would prefer/recommend the wiki, as GitHub Pages need a second branch and therefore need commits as well to maintain the documentation.

[jordanbrauer]

@apsoto I agree. Perhaps dividing the entire reference list into Common and Uncommon sections. Within those sections, divide the tags by use cases (like they already sort of are).

[joshbuchea]

Seems others would like to see this as well. I think this is a great idea! However, I think this is the kind of thing that happens over time. If people would like to begin submitting pull requests, we can get started on this. Please keep comments short & sweet so I can accept them!

[apsoto]

@joshbuchea yep, I don't consider myself enough of an expert with front-end, otherwise I would have :)

[niksmac]

IMO, lets do not complicate the simplicity of the page. What about creating another file with full details? This page need to be so minimal as it is now.

[FlorianWendelborn]

@niksmac I think we should probably just add a [explanation](explanation.md#something) to every entry. That'd be the best of both.

[FlorianWendelborn]

@tomlutzenberger sure, that's possible too, however I think it'd be basically useless if the entries don't link to the wiki/explanation.

[tomlutzenberger]

@dodekeract: Of course they should be linked. Other projects do it as well.

[joshbuchea]

Ok, some valid points & suggestions here. The README is growing to be unwieldy rather quickly. I'd like to consider and/or discuss this a bit more. Removed the help wanted label for now.

[FlorianWendelborn]

@tomlutzenberger both have a huge disadvantage compared to an explanation.md. You can't clone them. Maybe it'd be possible for the gh-pages, but then you'd have to setup a server or use your browser to view them.

Additionally, this project kind of only consists of documentation, so I don't think the additional documentation really counts as an argument in this case, since it's basically the goal of the project.

I therefore vote for option 3:

• An additional, more verbose, markdown file, which also contains explanation
  • linked by the README
  • easy to clone
  • probably a little bit harder to maintain

[beeva-miguelsarries]

So before every tag there is a comment with a brief explanation, ¿what about adding a link to that comment leading to a more in detail page?

[joshbuchea]

I'm closing this issue. Feel free to open pull requests if you feel an item or section needs more explanation.

[FlorianWendelborn]

@joshbuchea if somebody wants to add explanation, you should state which format you'd prefer.

[joshbuchea]

In most cases, I would prefer to see html comments placed with the associated tag(s).