Hacker News Reader

Comment by 1317 | Hacker News Reader

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

View on HN

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)

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!).

Your method is the most common I’ve seen. I also come across this style often:

> …using the File Transfer Protocol, or FTP.

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

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

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

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

Reply on news.ycombinator.com