Hacker News Reader

Comment by franciscop | Hacker News Reader

I am not sure if it's missing or it's part of one of these four, but another very important part for me is the introduction/README. Probably the most important one. Introductions include:

- Project health indicators, all green. [tests | passing] and such.

- Quick general description of the problem the project solves.

- A simple code snippet showing how easy it is to use it. Not the most complex way of using it as many do, please.

- Screenshots and gifs if it's UI-related. Very important if it's UI-related.

- Quick installation guide if using a common way, or a link to an in-depth guide if it's not easy to install.

- Links to other parts, in-depth articles, etc.

Some examples where I think I got it right (feedback welcome!): https://github.com/franciscop/server https://github.com/franciscop/ola

That said, good documentation takes a lot of effort and time.

View on HN

A great example of the simple code snippet is Flask https://palletsprojects.com/p/flask/

franciscop/server

> Powerful server for Node.js that just works so you can focus on your awesome project

This is not a "quick general description of the problem the project solves" and I don't even know what the code does after reading this. You can do better than this.

Agreed, I haven't liked that line for a while. What about something like this?

> A server for Node.js that works out of the box with modern Javascript

It is a Node.js server with a bunch of middleware so that you don't need to do common things like body-parser, cookies, etc. It's also based around async/await instead of callback-based, which makes it easier to work with more modern JS and that prevents me from calling something like "express wrapper" or similar.

My first problem is that "a server" only tells me it probably listens on a socket.

Is it a web server, a web framework, a PBX, telnet or general TCP, UDP or Unix socket support functions? Which protocols does it run? Is it a library? Is it a daemon?

It says so little, it could be literally anything.

I guess it has something to do with HTTP and I guess it's a library/framework because I guess a web developer wrote this, but only because it mentions JavaScript and doesn't specify further. But these are still just guesses, I wouldn't know from the text alone.

> works out of the box with modern Javascript

Does it work with other languages too, just not out of the box? If not, the "out of the box" doesn't add anything here. Doesn't similar code work out of the box anyway?

> Doesn't similar code work out of the box anyway

No, very notably both Express and its modern counterpart Koa don't work out of the box and devs using them have to learn, install and configure quite a few packages (middleware). This includes common functions like parsing the body of an HTTP request, parsing cookies, etc. This is the reason I created `server` in the first place, to do `npm install server` and not worry about these things on a per-project basis :)

Thanks for all the feedback, I'll replace "server" for "webserver" in my previous sentence. That alone is a great improvement over the current text IMHO.

Not GP but my question when I read this was “why not Express tho” and “modern JS” (as in ES6 imports etc) did click.

Instead of trying to over-simplify things for a nice one-liner:

> A server for Node.js that works out of the box with modern Javascript

Just give me the more verbose, but more conversational, explanation.

> It is a Node.js server with a bunch of middleware so that you don't need to do common things like body-parser, cookies, etc. It's also based around async/await instead of callback-based, which makes it easier to work with more modern JS and that prevents me from calling something like "express wrapper" or similar.

Sure it's more words, but I didn't have to think as much :)

That sounds like a marketing slogan, and honestly the JS ecosystem has so many of these that they've become meaningless.

What your thing looks to be is a wrapper over Node's `http` module, with a simplified API. "Powerful" is really not an appropriate adjective, since obviously your lib is limited to what the underlying Node's http module can do (and I'm going to go on a limb and guess that your library doesn't natively handle things like streaming or chunking or UPGRADE for web sockets or HTTP/2 push or N number of other things, considering you claim the library is also "simple").

Node.js web server that bundles and configures a lot of middleware so you don't have to. Or something along the lines. Instead of hinting what is the gist of how it works, say it straight away.

It seems to me that a good README is a summary of all four of his documentation types: it should have a brief explanation, a short how-to on getting started, a tutorial or usage example of the system, and a reference in the form of pointers to further documentation. And something he doesn't mention, graphics and screenshots!

> a good README is a summary of all four of his documentation types

Came here to say/reiterate this. A README is very flexible and can be any of the four types, the decision of which will depend on the contents of the repository and on what the README is trying to accomplish.

Half these things should be on the website for the project, not embedded in the source code attached to a readme file (where I might expect a link to the website, not a replacement for the website).

One thing I always want to see in a README: what command do I type to build and run this thing :P

That is not really docmentation. That's Github Geek Marketing. And sadly nowadays most thing published on Github stop there.

I don't really care what you call it. Sure, it's a lot like the sticker on the car window, but it's like business hours or a menu on a website--these are specific things to get me engaged and trivial things to let me kick the tires on a project.

If it's a UI toolkit, I'm not going to download, grab dependencies, and compile it, mock up a basic app just to find out it's the not something I want.

I don't deny it is useful. I just do not conflate it with proper Documentation.

- One sentence describing what a project does (preferably the first sentence of a README)

That should be the introduction (or other elements of) the Explanation, possibly of the Reference.

These suggestions generally correspond to document sections within the Linux Documentation Project HOWTOs, as an example.

> A simple code snippet showing...

And the variable naming to make clear what is user vs. system defined.

Reply on news.ycombinator.com