Update README.md

[marianelamin]

Add quick links at the top

[asciidiego]

Are internal links necessary? Normally I would be in favor of putting intra-document references, but Github implemented Table of Contents on README files and, in a code editor, what you really need (or what I think you need) is a Table of Contents. That way you can easily search and understand what's inside text files—like a book table of contents.

However, now that you put this here... manually creating table of contents como que da flojera no?

Perhaps what we need, instead of a TOC, is a creator of table of contents / CI script that prepeds table of contents in our MARKDOWN files automatically? What do you think? I think that sounds cool! Otherwise we have issues like the one pointed out by @VKorelsky. How do we know that the TOC is updated?

What do you all think? @marianelamin @VKorelsky

[asciidiego]

Another issue that is, perhaps, interesting to talk about is what kind of references should we use.

I think there is research that shows that putting hyperlinks in the text could reduce text comprehension—the irony, right?

So, I think we should strive to remove unnecessary links for our documents and make them look clean. What do you think?

For example, in this case, I am all in favor of putting a table of contents at the top of the file (all links in one place, where they do not distract, but help get where you want to read), but then avoid referencing other sections in the same text. For instance, imagine a section that ends with if you want to know how to connect to Angostura go to the Connection section. Is that section better with or without a link?

I know this might come off as persnickety, but since I am in charge of the CONTRIBUTING section of the repo I would like to, at least, discuss it!

Thanks~ ❤️

D

CC @dieko95 @Edilmo @marianelamin @VKorelsky

[marianelamin]

Whoohoo!! I like these comments. Actually, I was aiming to have a TOC at the top (like Angostura has, sort of) with links to documentation that we might consider important or as a starting point. Just to give it a bit more formality, like other repo's documentation I've seen. But I am open to suggestions.

I heard there was the possibility to link different files and condense them all in the read me. This would be the best way since we can maintain our doc with less effort.

How do we get it going, creator of table of contents / CI script?

[VKorelsky]

Perhaps what we need, instead of a TOC, is a creator of table of contents / CI script that prepends table of contents in our MARKDOWN files automatically?

The concept is nice but I think that for our small 52 line readme, it is overkill. Although it's true that the TOC might become outdated if we make very frequent changes to the readme, I don't think this will be a problem (readmes aren't typically frequently updated + it's a very small PR to update it should it become outdated). Let's only solve that problem when we need to :)

So, I think we should strive to remove unnecessary links for our documents and make them look clean. What do you think?

that should always be the goal with documents :)

[asciidiego]

I agree with @VKorelsky. But, for the record, there are ready-to-use scripts that can be integrated with Github Actions.

I'll leave it here for when the time comes!

https://github.com/ekalinin/github-markdown-toc#usage

---

although, expect many more README changes. Especially after these weeks.