DaemonForums  

Go Back   DaemonForums > Miscellaneous > Off-Topic

Off-Topic Everything else.

Reply
 
Thread Tools Display Modes
  #1   (View Single Post)  
Old 21st December 2014
raindog308 raindog308 is offline
Fdisk Soldier
 
Join Date: Sep 2011
Posts: 67
Talking 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.

Reply With Quote
  #2   (View Single Post)  
Old 21st December 2014
muflon muflon is offline
Fdisk Soldier
 
Join Date: Jul 2013
Location: Poland
Posts: 56
Default

I would say that in all BSD's documentation is done at high level.
Reply With Quote
  #3   (View Single Post)  
Old 21st December 2014
pawaan pawaan is offline
Fdisk Soldier
 
Join Date: Jan 2013
Posts: 82
Default

Quote:
I would say that in all BSD's documentation is done at high level.
True but I find gentoo guite great in this area too.
Reply With Quote
  #4   (View Single Post)  
Old 21st December 2014
Oko's Avatar
Oko Oko is offline
Rc.conf Instructor
 
Join Date: May 2008
Location: Kosovo, Serbia
Posts: 1,102
Default

Unfortunately the quality of documentation vary greatly among BSDs and it is a typical first indication of the health and strength of particular community (I am not thinking here just four core BSDs but also derived distros like flashrd for OpenBSD or pfSense, FreeNAS, PC-BSD/TrueOS for FreeBSD). I don't want to trash Linux too much as things vary wildly across districts and applications. One example that I am very familiar with of stellar documentation is OpenVPN project which is much more closely associated with Linux.
Reply With Quote
  #5   (View Single Post)  
Old 22nd December 2014
muflon muflon is offline
Fdisk Soldier
 
Join Date: Jul 2013
Location: Poland
Posts: 56
Default

Quote:
Originally Posted by Oko View Post
Unfortunately the quality of documentation vary greatly among BSDs and it is a typical first indication of the health and strength of particular community (I am not thinking here just four core BSDs but also derived distros like flashrd for OpenBSD or pfSense, FreeNAS, PC-BSD/TrueOS for FreeBSD).
Moin!

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:
The finger command appeared in 3.0BSD.
b) FreeBSD -
Quote:
The finger command appeared in 3.0BSD.
c) OpenBSD -
Quote:
The finger command appeared in 2BSD.
In these case OpenBSD simply win, because It's true that finger program first appeared in base of 2nd BSD; that was created in times when Unix Seventh Edition appeared .

On next example, let's see man 1 who;
a) NetBSD -
Quote:
A who utility appeared in Version 6 AT&T UNIX.
b) FreeBSD -
Quote:
A who command appeared in Version 1 AT&T UNIX.
c) OpenBSD -
Quote:
A who utility appeared in Version 1 AT&T UNIX.
According to the first edition of the Unix Programmer's Manual; FreeBSD and OpenBSD man pages are true, NetBSD is wrong.

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.
Reply With Quote
  #6   (View Single Post)  
Old 22nd December 2014
ibara ibara is offline
OpenBSD language porter
 
Join Date: Jan 2014
Posts: 783
Default

Quote:
Originally Posted by muflon View Post
In these case OpenBSD simply win, because It's true that finger program first appeared in base of 2nd BSD; that was created in times when Unix Seventh Edition appeared.
Quote:
Originally Posted by muflon View Post
According to the first edition of the Unix Programmer's Manual; FreeBSD and OpenBSD man pages are true, NetBSD is wrong.
I take it your diffs for those man pages are already on the way to both FreeBSD and NetBSD, and just got lost in the mail?
Reply With Quote
  #7   (View Single Post)  
Old 22nd December 2014
muflon muflon is offline
Fdisk Soldier
 
Join Date: Jul 2013
Location: Poland
Posts: 56
Default

Quote:
Originally Posted by ibara View Post
I take it your diffs for those man pages are already on the way to both FreeBSD and NetBSD, and just got lost in the mail?
No. I never pointed that out on mailing list.
Reply With Quote
  #8   (View Single Post)  
Old 22nd December 2014
ibara ibara is offline
OpenBSD language porter
 
Join Date: Jan 2014
Posts: 783
Default

Quote:
Originally Posted by muflon View Post
No. I never pointed that out on mailing list.
I imagine both projects would like to have those fixed.
Reply With Quote
  #9   (View Single Post)  
Old 22nd December 2014
scottro's Avatar
scottro scottro is offline
Real Name: Scott Robbins
ISO Quartermaster
 
Join Date: Apr 2008
Location: NYC
Posts: 652
Default

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.
Reply With Quote
Old 22nd December 2014
Oko's Avatar
Oko Oko is offline
Rc.conf Instructor
 
Join Date: May 2008
Location: Kosovo, Serbia
Posts: 1,102
Default

Quote:
Originally Posted by ibara View Post
I imagine both projects would like to have those fixed.
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.
Reply With Quote
Old 23rd December 2014
ibara ibara is offline
OpenBSD language porter
 
Join Date: Jan 2014
Posts: 783
Default

Quote:
Originally Posted by Oko View Post
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.
I wouldn't be so sure about this. FreeBSD at least pays lip service to the necessity of correct documentation through the division of labor of their developer team: one has a src, ports, or doc commit bit (of course, one can have multiple).

Quote:
Originally Posted by Oko View Post
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.
(Perhaps you should send something then.)

Quote:
Originally Posted by Oko View Post
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.
This is not an excuse for not sending patches.
Reply With Quote
Old 23rd December 2014
J65nko J65nko is offline
Administrator
 
Join Date: May 2008
Location: Budel - the Netherlands
Posts: 4,125
Default

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
Reply With Quote
Old 23rd December 2014
roddierod's Avatar
roddierod roddierod is offline
Real Name: Rod Person
VPN Cryptographer
 
Join Date: Apr 2008
Location: Pittsburgh, Pa
Posts: 437
Default

Quote:
Originally Posted by scottro View Post
I remember people laughing at how bad MS help pages were, and then around Win2k, they actually began to get pretty useful.
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
Reply With Quote
Old 23rd December 2014
scottro's Avatar
scottro scottro is offline
Real Name: Scott Robbins
ISO Quartermaster
 
Join Date: Apr 2008
Location: NYC
Posts: 652
Default

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.
Reply With Quote
Old 23rd December 2014
muflon muflon is offline
Fdisk Soldier
 
Join Date: Jul 2013
Location: Poland
Posts: 56
Default

Quote:
Originally Posted by ibara View Post
I imagine both projects would like to have those fixed.
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
Reply With Quote
Old 24th December 2014
thirdm thirdm is offline
Spam Deminer
 
Join Date: May 2009
Posts: 248
Default

Quote:
Originally Posted by scottro View Post
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.
I wouldn't say atrocious but it's not good. Some disagree on this argument, but I attribute it partly to these javadoc-like embedded documentation extractors. They change the problem from thinking about what needs to be communicated, confronting an empty page, to plugging in smidgens of text in each of the required places, i.e. before each class and method. If someone's very diligent and weighs the result that may not be so bad. But normally what you have is a skeleton of documentation with important issues not addressed. And at the lowest points you have the same information that's in the class and method names, and no more, repeated with articles and prepositions added.

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.
Reply With Quote
Old 24th December 2014
roddierod's Avatar
roddierod roddierod is offline
Real Name: Rod Person
VPN Cryptographer
 
Join Date: Apr 2008
Location: Pittsburgh, Pa
Posts: 437
Default

Quote:
Originally Posted by thirdm View Post
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
Reply With Quote
Old 24th December 2014
ibara ibara is offline
OpenBSD language porter
 
Join Date: Jan 2014
Posts: 783
Default

Quote:
Originally Posted by muflon View Post
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.
Sending diffs should come first; it won't interfere with any research you're trying to do and will get documentation fixed.
Reply With Quote
Old 28th December 2014
muflon muflon is offline
Fdisk Soldier
 
Join Date: Jul 2013
Location: Poland
Posts: 56
Default

Quote:
Originally Posted by ibara View Post
Sending diffs should come first; it won't interfere with any research you're trying to do and will get documentation fixed.
Christos Zoulas from NetBSD project reported to me that he include changes in man pages that I mention above; e.g. man 1 who

I will inform also FreeBSD project with the finger manual.

Salut,
Marcin
Reply With Quote
Reply

Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump

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


All times are GMT. The time now is 05:23 AM.


Powered by vBulletin® Version 3.8.4
Copyright ©2000 - 2024, Jelsoft Enterprises Ltd.
Content copyright © 2007-2010, the authors
Daemon image copyright ©1988, Marshall Kirk McKusick