191–200 of 203 posts
[1]: https://lightbus.org
Back in the early days, the printed manuals for Research Unix and BSD consisted of two volumes. Volume 1 was the reference and consisted of all the man pages for every command (section 1), system call (section 2), library function (section 3), etc. Volume 2 contained longer documents - what this article calls tutorials, how-tos, and explanations. The man command let you read all the pages in volume 1. Volume 2 only e…
Of course, sparse or arcane documentation also leads to proliferation of educating books, by people ready to help for a reasonable sum. The existence of which market should say something about the truthfulness of ‘manpages are enough.’
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 man…
That is not really docmentation. That's Github Geek Marketing. And sadly nowadays most thing published on Github stop there.
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.
Earlier quoted context omitted.
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 callin…
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 thi…
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.
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 man…
Back in the early days, the printed manuals for Research Unix and BSD consisted of two volumes. Volume 1 was the reference and consisted of all the man pages for every command (section 1), system call (section 2), library function (section 3), etc. Volume 2 contained longer documents - what this article calls tutorials, how-tos, and explanations. The man command let you read all the pages in volume 1. Volume 2 only e…
Notably, Linux had a whole lot of howtos and faqs—not sure about authoritative sources but I guess The Linux Documentation Project is/was the largest. That was how people learned to do stuff without tearing their hair out, in the early–mid-2000s. I probably still have some of them lying around thanks to stockpiling like the apocalypse is nigh. Of course, sparse or arcane documentation also leads to proliferation of e…
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 man…
Earlier quoted context omitted.
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 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 man…
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!
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.