|
|||
Documentation Quality Compared
Spent the weekend working on both Linux and OpenBSD. I made a picture that summarizes my feelings on the documentation quality of each.
|
|
|||
I would say that in all BSD's documentation is done at high level.
|
|
|||
Quote:
|
|
|||||||
Quote:
I have CSRG Archive that includes four CD-ROMs, created by Dr. Marshall Kirk McKusick. I use It as a main reference to almost all man pages I'm interested With. All core distributions goes with their main list of software that is included in base installation. And If you look closer for e.g. at history part in some manuals You can find differences like in; man 1 finger; a) NetBSD - Quote:
Quote:
Quote:
On next example, let's see man 1 who; a) NetBSD - Quote:
Quote:
Quote:
OpenBSD man pages are one of the most accurate e.g. in history notation. Ingo Schwarze [I posted few 'pdf's' written by Him on OpenBSD - papers... ] is very precise in doing those "small notes" with the right way. But in therms of "flavours" or quality of manuals; NetBSD, FreeBSD and OpenBSD are unique in some parts. For example NetBSD; man 9 intro, which presents list of 'tools' that are related to kernel internals. Compare this with man 9 intro in OpenBSD and FreeBSD. Salut, Marcin Last edited by muflon; 22nd December 2014 at 02:09 PM. |
|
|||
Quote:
Quote:
|
|
|||
No. I never pointed that out on mailing list.
|
|
|||
I imagine both projects would like to have those fixed.
|
|
||||
The gap between the BSDs and Linux documentation, in my opinion, has narrowed. A lot of Linux man pages these days actually have examples. I think the gap was much wider in the mid 2000's.
It's possible I just know more now than I did then, so that they seem less incomprehensible, and maybe it's just a matter of the wider availability of tutorials written by relatively inexperienced people, aimed at those without great understanding. I think all documentation has improved, actually--I remember people laughing at how bad MS help pages were, and then around Win2k, they actually began to get pretty useful. |
|
||||
I would not bet on it If people cared so much about man pages and their Handbook/Guide they would update those for every major release. In my experience OpenBSD is the only project which consider lack of documentation a bug. There are many cool pkgsrc features for example that are not documented even though pkgsrc has pretty extensive documentation. Another thing is who is actually allowed to update documentation.
You can be sending patches all they long if the developer with commit access doesn't react or she/he thinks that there is nothing wrong with the documentation. |
|
|||
Quote:
Quote:
This is not an excuse for not sending patches. |
|
|||
IIRC Oko had a very traumatic experience with the FreeBSD porter responsible for the FreeBSD port of Donald Knuth's TeX. That developer refused any help like looking at the OpenBSD TeX port and as a result FreeBSD did not have any TeX for many years.
__________________
You don't need to be a genius to debug a pf.conf firewall ruleset, you just need the guts to run tcpdump |
|
||||
I lot of the .NET documentation is still hilarious, IMO.
__________________
"The basic tool for the manipulation of reality is the manipulation of words. If you can control the meaning of words, you can control the people who must use the words." -Philip K. Dick |
|
||||
I've heard that from other programmers too--that their programming documentation is still pretty atrocious. Not being a programmer, I wouldn't know--their sysadmin stuff is often pretty useful though. At my old job, I remember one day, the Windows admin was out and we needed to do something, just typed a few words into help and it gave a nice page with examples, making it easy to do. Though I've not had to do any Windows administration in a year and a half, so I don't know the current state.
|
|
|||
Moin Ibara;
Yes I will inform about My findings FreeBSD and NetBSD projects. But first of all, I need to finish my research related to "man heritage" - and at the end I would like to publish paper related to this. Greetings To You, Marcin |
|
|||
Quote:
Then again Perl's documentation is often embedded (however, the flexibility is much greater so it doesn't all have to be) and I think it's fantastic (though how much does that have to do with a certain individual by the name of Tom Christiansen?). Maybe it's more only about how much the people writing it -- or the people paying the people writing it -- care. Obviously, when things are done only for commercial reasons you're back to a cost benefit analysis. Microsoft's documentation is probably now at the level of quality where putting more effort into it can't be justified in terms of increased profits. |
|
||||
That's an excellent point...never really thought about that in terms of documentation.
__________________
"The basic tool for the manipulation of reality is the manipulation of words. If you can control the meaning of words, you can control the people who must use the words." -Philip K. Dick |
|
|||
Sending diffs should come first; it won't interfere with any research you're trying to do and will get documentation fixed.
|
|
|||
Quote:
I will inform also FreeBSD project with the finger manual. Salut, Marcin |
|
|
Similar Threads | ||||
Thread | Thread Starter | Forum | Replies | Last Post |
softraid crypto compared to geom_eli (geli) | hanzer | OpenBSD Security | 10 | 26th December 2013 01:49 AM |
PDF: Quality of Document Rendering on BSDs | vermaden | Off-Topic | 32 | 29th May 2011 05:07 PM |
Quality and Backwards Compatibility of GNU Tools ... | vermaden | Off-Topic | 1 | 12th May 2009 08:25 PM |
Comparison of Code Quality | JMJ_coder | Other BSD and UNIX/UNIX-like | 13 | 11th April 2009 03:40 AM |
ZFS stability compared to Solaris | tanked | FreeBSD General | 5 | 26th October 2008 05:43 PM |