3 ms·

i make these headings and write down the answers: what is it how do i install it how do i use it any "pro-tips"/useful stuff to know how do i get h

by 1317 2y ago

i make these headings and write down the answers: what is it how do i install it how do i use it any "pro-tips"/useful stuff to know how do i get help (optional) acknowledgements etc (optional) too often i see things skip the "what is it" part

emilamlom 2y ago
I would also say in the "what is it" part that projects intended for a broad audience should avoid jargon as much as possible. It's frustrating in my experience to have to google several acronyms before I can even tell what the purpose is. (Security projects/programs are notorious for using way too many acronyms for example)
- j1elo 2y ago
  My rule for writing documentation is as follows: first use of a commonly abbreviated term is written in its complete form, with the acronym or short form in parentheses. Then, the rest of the text in that same page can freely use the shorter form as needed. So "the File Transfer Protocol (FTP) is bla bla... When using FTP, remember to bla bla..." I think that's the most structured and correct way to introduce an acronym. Another style is to use "short form (long)" but "long form (short)" feels better to me (although I'm not a native speaker so maybe I got it the other way around!).
  - kstrauser 2y ago
    Your method is the most common I’ve seen. I also come across this style often: > …using the File Transfer Protocol, or FTP.
tregoning 2y ago
It would be nice if the app would allow us to save templates (no need to get fancy just via URL params e.g. for the above it would be something like:`?sections=title&Desc,installation,runLocally,Support,Authors,Ack,usageExamples` That way we could just generate a 'template' that we can share/save etc
lost_my_pwd 2y ago
A few more more, depending on the nature of the project and one's goals: how do I report bugs how do I build from source how can I help/contribute
eternityforest 2y ago
Sometimes they skip the how to install it and how to use it part too...
zvr 2y ago
I appreciate it when there is also a "License" section in the README itself.

by 1317 2y ago

emilamlom 2y ago

I would also say in the "what is it" part that projects intended for a broad audience should avoid jargon as much as possible. It's frustrating in my experience to have to google several acronyms before I can even tell what the purpose is. (Security projects/programs are notorious for using way too many acronyms for example)

j1elo 2y ago
My rule for writing documentation is as follows: first use of a commonly abbreviated term is written in its complete form, with the acronym or short form in parentheses. Then, the rest of the text in that same page can freely use the shorter form as needed. So "the File Transfer Protocol (FTP) is bla bla... When using FTP, remember to bla bla..." I think that's the most structured and correct way to introduce an acronym. Another style is to use "short form (long)" but "long form (short)" feels better to me (although I'm not a native speaker so maybe I got it the other way around!).
- kstrauser 2y ago
  Your method is the most common I’ve seen. I also come across this style often: > …using the File Transfer Protocol, or FTP.

tregoning 2y ago

It would be nice if the app would allow us to save templates (no need to get fancy just via URL params e.g. for the above it would be something like:`?sections=title&Desc,installation,runLocally,Support,Authors,Ack,usageExamples` That way we could just generate a 'template' that we can share/save etc

lost_my_pwd 2y ago

A few more more, depending on the nature of the project and one's goals: how do I report bugs how do I build from source how can I help/contribute

eternityforest 2y ago

Sometimes they skip the how to install it and how to use it part too...

zvr 2y ago

I appreciate it when there is also a "License" section in the README itself.