Date: Fri, 16 Mar 2001 06:56:09 -0800 From: richard childers <fscked@pacbell.net> To: Doug Young <dougy@bryden.apana.org.au> Cc: Duke Normandin <01031149@3web.net>, David Johnson <djohnson@acuson.com>, Mike Meyer <mwm@mired.org>, mij@osdn.com, freebsd-questions@FreeBSD.ORG Subject: Re: documentation issues generally Message-ID: <3AB22989.5B28111C@pacbell.net> References: <046701c0ab3c$c4a66300$847e03cb@apana.org.au>
next in thread | previous in thread | raw e-mail | index | archive | help
"Its quite obvious that the "official" docs people are more interested in the systems used to create docs than the content thereof. " I suspect the seed of this lies in a certain hostility, on the part of programmers, towards those whom are not interested in wrestling with code, but whom would rather build things using the provided modules; dare I call it elitism? Let's call it a fundamental assumption of inequality. FreeBSD probably could have addressed this, early in its existence, by adapting into the team, a few people whose job was, not to write code, but to work with the developers and to insure that their (often incoherent) documentation was turned into sequential, step-by-step instructions. Alas, this did not happen; I know of at least one formal application to cdrom.com that was never replied to (mine), when they were looking for a person to administer and organize the (at that time, increasingly confusing) FTP site, and write documentation. C'est la vie. (-: See what happens when you make decisions based upon hearsay? I think it's probably too late. FreeBSD has alienated a lot of people with the "if you can't read the man pages then you probably aren't smart enough to work with us and never mind what grades I received in my writing classes" approach. I approve of the authors whom have undertaken to write their own books (even if I may object to how they market the results :-); alas, I suspect that even they did not get full access to the FreeBSD development team, or complete cooperation from everyone whom had written code. But it's an old problem; I'm sure I've seen it at two dozen different sites, over the years; the credo of 'get it working and we'll write the documentation later'. Right. Sure you will. But, let's face it; it's an industry-wide problem. Many Solaris man pages haven't changed for years, perhaps even a decade, despite obvious changes in the functionality. Documentation does not pay for itself, from the point of view of an MBA. The people making the decisions to buy or not buy are fundamentally incapable of appreciating the contents of manuals; anything over 10 pages long is a book to them, they prefer pamphlets that show you how to plug it in and really don't understand why anything more should be required. (-: And as long as companies charge for support contracts, there will be a disincentive towards providing accurate, detailed manuals. Support contracts pay for the Technical Support department's costs, putting a smile on the faces of MBAs everywhere. Perhaps FreeBSD should spin off a for-profit support group - small, to start - whose profits are fed into producing a better base of documentation; READMEs, FAQs and the like, written by professionals trained in articulating complex issues. But I suspect that's what the merge with BSDi will produce. I hope so, anyway. -- richard Doug Young wrote: > Seems like the docs situation is destined to keep going the same route as > present. Its quite obvious that the "official" docs people are more > interested in the systems used to create docs than the content thereof. The > result is that more & more users (recalling their own difficulty with the > official formats) will establish sites like freebsddiary / bsdvault / > mostgraveconcern / freebsdzine / etc etc to cater for those who (quite > rightly) believe that the official stuff is aimed at the geekship. > > I personally don't believe there is any point in submitting material to > freebsd-docs ... I favour an infinitely more user-friendly format (eg > including a bunch of screen dumps, step_by_step examples & "real world" > examples of typical commands) rather than the mind numbing synopsis > style complexity of the man pages. Maybe the man pages aren't the "correct" > place for explicit explanations, but if thats the case then the Handbook > certainly is. To be fair its definitely an improvement on what it was a year > ago & light years ahead of most of the linux equivalents, however the screen > dumps /examples / etc are still conspicuous by their absence. OK so some of > the user-friendly sites have errors .... at least they make an honest > attempt to provide information in an intelligible form which is something > still lacking in the official documentation. > > To Unsubscribe: send mail to majordomo@FreeBSD.org > with "unsubscribe freebsd-questions" in the body of the message -- Richard A. Childers Senor UNIX Administrator fscked@pacbell.net (email) 415.664.6291 (voice/msgs) # Providing administrative expertise (not 'damage control') since 1986. # PGP fingerprint: 7EFF 164A E878 7B04 8E9F 32B6 72C2 D8A2 582C 4AFA To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-questions" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?3AB22989.5B28111C>