readme TOCs + formatting

[tomhuhges]

(intro: i've never contributed to open source before but want to get involved - dwyl looks like a great place to get started. hi!)

quite a lot of the dwyl readmes are really daunting to look at. and i feel it would be good to add a table of contents to the top of each one, so you can immediately see what you're about to read and jump to parts that interest you, or to make things easier to find later on, or to make it easier to see if a readme is missing any sections.

in terms of formatting, they could make use of horizontal rules to separate sections of text. there's also an insane overuse of italics, but that might just be my personal opinion...

as a first contribution, i'm willing to go through some repos (starting with this one) and tidy up the readmes (making sure not to change any of the content).

let me know if you think this is worthwhile + feel free to add any other suggestions. ✌🏻

[nelsonic]

Hi @tomhuhges, thank you for raising this issue! ❤️ 🎉 (seriously, it means a lot to us!) I could not agree more! 😞 The dwyl learn-... readmes are (reasonably) content rich ⭐️ but lacking in style, layout, cohesion and "flow". 😧

They were mostly written by someone who is dyslexic and whose first language is not English. 😉 (i.e. not someone with a degree in Linguistics... 😮 that's awesome BTW!)

They all need some serious editorial attention (yes, I use italics "too much" but only because I don't know how else to emphasise words as there isn't an underline feature in markdown... my objective isn't to make the text look wierd/ugly it's to make it "scannable" so people can extract important bits fast...) 👀 ⏩

If you are up for helping us re-org the readmes start-here would be a logical place to start. The content is meant to be for/by the community. We just try to get it started and into a useable state. None of us are "precious" about what we have written in docs/readmes or code, so feel free correct grammar, pair back on any surplus words, improve sentence structure, or rip out rambling sections if they don't add any value!

Conclusion: Go for it! 🚀

@iteles is our resident readme reviewer (but is quite busy trying to run a couple of companies so doesn't have much time ... so it would be amazing if you can pick this up and run with it!) @NataliaLKB, @msmichellegar, @claireinez, @jsms90 & @bradreeder are all exceptionally eloquent/proficient in English, highly technically skilled and have an eye for keeping things beginner-friendly... 😍 so you could assign your Pull Request(s) for review to any/all of them. They have read all (or most of) the learn-... repos so if you have any specific questions, don't hesitate to ask! please don't take it personally if takes a few hours for a reply as everyone is super busy ... ⏳ (I may answer the odd question out of excitement to see improvement, but for the most part will be focussed on project work also, I'm definitely not the best person to ask about anything related to revising the content, I practically flunked English in "formal" education!! 🤣 )

Thanks again!

P.S: We have a roughly <ol> for new people to follow: https://github.com/dwyl/the-book/issues/69

Most of the "introductory" content is still "in progress", but many of the "intermediate" stuff is already in a useable state, but still poor from an editorial standpoint ... e.g: https://github.com/dwyl/learn-tdd which is "popular" but could use a lot of help/tidying...

Our long-term aim is to "assemble" all the various readmes into a cohesive "book" that people can download and read on their e-reader/phone on the transport to their current (boring) work (and then try the examples when they get back to their PC), so having better editorial to make things consistent would be amazing!!

[tomhuhges]

great!

the content from what i've seen so far is pretty awesome so i don't think it needs much. but i'll take a look to see if anything needs doing.

also i could have used a better word than 'insane' to describe the italics, so apologies for that. i meant 'quirky' 🙃

[YvesMuyaBenda]

Suggestion: a style guide (say an agreed upon set of rules) might make it more easy for folk to contribute to this particular effort without creating clashes. For example, add a table of contents at the top of each readme , etc, etc.

[jruts]

Here is a repo with some beautiful README files:

https://github.com/matiassingers/awesome-readme

What I conclude here is that bold is used to emphasize words, not italic. The usage of normal, italic and bold in the same sentences are, in my opinion, not really that readable.

Just my 2 cents.

[tomhuhges]

agree about a style guide, as long as it's not too strict. if i have a go at reformatting the start-here readme then i could use points i come across from that and incorporate them into a style guide.

i think this could also be an accessibility issue. gov.uk's guidelines for accessible text has the following:

Avoid italics, underlining, simulated handwriting, unusual shaped letters and decorative typefaces.
Avoid using blocks of capital letters in titles or body text.

[newswim]

I agree with the majority of what everyone's saying, but wanted to throw in a word about appreciating the semi-manic-like formatting style that most dwyl repos have currently. The 'talk-like' nature conveys a lot of information without needing to repeat things for emphasis. I read a lot of educational material and these automatically stood out to me as being written by humans, who were excited about what they're talking about. They are also, as Nelson pointed out, highly "scannable". I think you raise a really good point, Tom (and your website rules 🌟 🌟 🌟 ). It's also my personal hope that we can try to retain a similar voice when improving these. Also +1 for helping/reviewing anything I can. I was a CW major and have done a fair amount proof-reading in the past.

[mattlub]

I just stumbled upon this issue after thinking one (and in fact all) of the READMEs were crying out for a Contents section. I then thought about creating a script which would auto-generate one based on headings and then found that of course someone has already done so 😄 - see doctoc

I tried it out on a README and with minimal tweaking got good results (see image below)- any thoughts on this? Is there general agreement that READMEs (especially big ones) are more readable with a contents section?

[iteles]

@mattlub I was writing about this on a different repo a month ago: https://github.com/dwyl/alc/issues/15#issuecomment-298250086

I think we absolutely need this, as you say, particularly on big readmes: https://github.com/dwyl/learn-tachyons/issues/26

Looks like it will require a little tweaking because we use a lot of different levels of titles to make sure it's easy to link to specific steps in the readmes. I think this is fantastic and has helped me a lot when linking people to things (I really miss it on repos that use bold instead of ####) but means we'll need to get rid of some of the contents bullets - above, I think it's the steps 1-6 that are too much for Contents Guides.

🎉 PRs welcome!

[mattlub]

@iteles ok sure- still even with the tweaking, I reckon it takes under 5 minutes with the tool.

The only possible problem is if new sections/headings get added in the future, they would have to be either manually added to the contents, or the tool would have to be used again and then the tweaking would have to be redone. Maybe a guideline for how the contents sections should look would be required to maintain consistency.

I'll do a PR on Tachyons anyway and see what you think.