9 ms·
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
by franciscop 7y ago
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/server https://github.com/franciscop/ola https://github.com/franciscop/ola
That said, good documentation takes a lot of effort and time.
- anaphor 7y agoA great example of the simple code snippet is Flask https://palletsprojects.com/p/flask/ https://palletsprojects.com/p/flask/
- pstuart 7y ago> A simple code snippet showing... And the variable naming to make clear what is user vs. system defined.
- qplex 7y ago- One sentence describing what a project does (preferably the first sentence of a README)
- swinglock 7y agofranciscop/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.
- franciscop 7y agoAgreed, 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.
- swinglock 7y agoMy 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?
- franciscop 7y ago> 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.
- arcturus17 7y agoNot GP but my question when I read this was “why not Express tho” and “modern JS” (as in ES6 imports etc) did click.
- dredmorbius 7y agoThat 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.
- ldng 7y agoThat is not really docmentation. That's Github Geek Marketing. And sadly nowadays most thing published on Github stop there.
- pfranz 7y agoI 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.
- ldng 7y agoI don't deny it is useful. I just do not conflate it with proper Documentation.
- Shish2k 7y agoOne thing I always want to see in a README: what command do I type to build and run this thing :P
- yspeak 7y agoYou forgot one which is to tell what it is. I don't know how many project pages I've seen that don't tell you what it does or even give a good hint. Even after reading several pages into the documentation. It sends the message that it's only for people in the know and others are not welcome without becoming an expert in the code.
- yardshop 7y agoIt 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!
- ricc 7y ago> 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.
- saurik 7y agoHalf 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).