[proposal] Update and automate documentation

[papierkorb]

[proposal] Update and automate documentation

[Papierkorb]

Back then, I chose the README as main documentation hub (Along the TEMPLATE.yml) for four reasons:

1. It's easily Ctrl+F'able, or in less keyboard-terms, easily discoverable through means everyone knows
2. It's part of every checkout and will always reflect the state your checkout is in
3. It's harder to get out of date as developers simply see it more often. A wiki page is quickly forgotten. (Yet to find a non-dusty Github Wiki page myself)
4. The user is guaranteed to have a copy of it available

A source of inspiration was the README of https://github.com/sinatra/sinatra, which may be longer than the bible (Haven't checked). Still, using Ctrl+F I can quickly find what I was looking for, both online and offline. Has been a few years so don't remember anymore, but I once saw a talk on YouTube where the talker explicitly used Sinatra as example.

This is not to dissuade anyone of proposing against these points, just what my reasons were back then.

[kalinon]

@Papierkorb all good reasons! Perhaps a table of contents at the top? Its great documentation so wanted to make sure its easily accessible and we can identify any places that need updating easily as well.

[Papierkorb]

Ah sure, a TOC would be splendid

[docelic]

Added ToC to the README using a script from "github-markdown-toc" repository.

[docelic]

For TEMPLATE.yml, to suit everyone's preferences it looks like we'd need three versions of it:

1. Just the documentation, extracted into some standard documentation format (e.g. Markdown)
2. TEMPLATE.yml, unchanged, as it is currently
3. TEMPLATE.yml, containing only example config (no documentation, or at least not longer that 1-2 lines per section)

And again/also with the ToC added to the first one (or two) items from the list.

I am going to see how easy/convenient it would be to write a script that produces all this from ideally a single format (maybe from the current TEMPLATE.yml or similar).

(@kalinon if you had a preference/intention to work on this yourself, let me know of course.)

[kalinon]

I changed the title to more reflect what we are thinking. @docelic you are good, it was more of a thought i had. I will use github-markdown-toc for some of my other projects tho!

[docelic]

I've tried converting the documentation from TEMPLATE.yml into Markdown. The results are good and I plan to add this as file CONFIGURATION.md.

An example can be seen here:
https://github.com/docelic/bindgen/blob/master/CONFIGURATION.md

At least for now I've given up on trying to automate this as I think these things will rarely change, and "normal", elaborate documentation is a necessity for any project.

(We can still keep all the comments in TEMPLATE.yml of course; these ideas are not in conflict.)

[kalinon]

I like it!

On Thu, May 28, 2020 at 5:39 PM Davor Ocelic ***@***.***> wrote: I've tried converting the documentation from TEMPLATE.yml into Markdown. The results are good and I plan to add this as file CONFIGURATION.md. An example can be seen here: https://github.com/docelic/bindgen/blob/master/CONFIGURATION.md — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#55 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABK6J3CONUWEYAZIYITVHRDRT3KYZANCNFSM4NMLICFA> .

-- *Holden Omans*