Date: Fri, 16 Mar 2001 09:27:14 -0800 From: "Ted Mittelstaedt" <tedm@toybox.placo.com> To: "richard childers" <fscked@pacbell.net>, "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: <010301c0ae3e$577a1d80$1401a8c0@tedm.placo.com> In-Reply-To: <3AB22989.5B28111C@pacbell.net>
next in thread | previous in thread | raw e-mail | index | archive | help
>-----Original Message----- >From: owner-freebsd-questions@FreeBSD.ORG >[mailto:owner-freebsd-questions@FreeBSD.ORG]On Behalf Of richard >childers >Sent: Friday, March 16, 2001 6:56 AM >To: Doug Young >Cc: Duke Normandin; David Johnson; Mike Meyer; mij@osdn.com; >freebsd-questions@FreeBSD.ORG >Subject: Re: documentation issues generally > > > >"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. > I disagree with this. Rather, the problem is that programmers usually dislike "wasting time" on writing documentation. All of them that I've worked with are more than happy to have someone else do it. But, I've not sensed that anyone I've worked with has "looked down" on what I'm doing. I've written professionally before on a software development team, not just doing the book but before that. The problem is that there is a line between writing the docs and writing the code. Many newbie documentation authors are under the impression that their job is strictly to stay on the "writing docs" side of the line. In short, it's the attitude that "I have an English degree and I don't know anything about that software code writing stuff" Then, they expect the programmer to not only do all the writing of the code, but to frequently cross over the line to writing the docs because "after all he knows what he did with the code" This is obviously unfair, and it's very annoying to the developer as you can imagine. The best documentation comes from doc writers who have the attitude that they will cross over the line into the programmers realm. For example, when I was at Central Point Software, one of the major groups that contributed many, many early bug reports was the tech writers! And, not only did they just contribute simple "I clicked here and it blew up" type of reports, but they actually were very familiar with the program structure, and knew as much about it as the coders did, and would frequently identify the specific module that was broken and where it broke and who broke it and why it was broken. In another example, I remember being in a meeting where the tech writers were telling the upper management that the coders were going down a dry hole - they were working on Win95 code and needed to write the particular piece as a VxD, and the programmers working on the module didn't even know what a VxD was! >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. > Do you know just how difficult it is to find such people? The good doc writers that can do this are scarce as hens teeth. The FreeBSD project has to work with what comes in the door - and if nobody like this came into the door early on, then they couldn't do anything about it. >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. > cdrom.com <> The FreeBSD Project. Your welcome to hammer on cdrom.com as much as you like but membership in The FreeBSD Project is open to anyone who is willing to demonstrate they can do the work. >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 don't understand this at all. The FreeBSD Project and BSDi have never adopted this as an official policy. What your talking about is the attitude of some individuals in the movement. However not all individuals have this attitude and it's unfair to tar everyone with the same brush. >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. > Thanks, but as a matter of fact I had a tremendous amount of cooperation, considering what I was asking people to do. Sure, not everyone completed the review cycle, but I can recall one instance where I specifically requested one of the busier core team members to review the mail chapter and they complied without complaints. (and I was very glad they did) The help during the review cycle that I did get was very significant and invaluable. >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. > I agree that many software firms have this attitude and it's a very bad one, because there's an implication there that the development group is mandated to produce good documentation, and they are deliberately violating it. When you purchase a commercial software package the seller is certainly obligated to make complete documentation available. But, FreeBSD doesen't have this attitude. Rather, their attitude is: "get it working and we'll write the documentation if we have time" and this is perfectly fair - FreeBSD is NOT a commercial software package and the group has no such implied obligation to produce complete documentation because they are handing out the source code. In a limited time situation given a choice between having either the docs or the running software program, at least some of the people will benefit from the program if that is all there is, but nobody will benefit from the docs if the docs are all there is. About the ONLY documentation obligation that I feel the FreeBSD Project is morally obligated to meet is to write good, self-documenting code. We've all seen horrible C code where all variable names in the program are single-letter and you don't see a single comment in 10,000 lines of code. Some of the ports are like this. But I don't think that the BSD kernel is that bad. >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. That is because Solaris puts that information into the AnswerBooks and other publications, not man pages. And I agree that not documenting in man pages is horrible - I deplore the GNU's attitude with GCC for example where the second paragraph is basically a threat to stop distributing the man page if people complain that it's incomplete. What an attitude. 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. (-: > That market is not the FreeBSD market, and your not going to be successful marketing a system like FreeBSD into it. But, there's enough people out there that know better now, that projects like FreeBSD can survive. The biggest marketing problem is getting those folks connected with FreeBSD. >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. > No, this is wrong too because where do you think the Support department get's _it's_ information you don't think they allow the support people in to talk to the developers, do you? Sheesh! Without good docs your support department is going to suck and nobody is going to pay for that. >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. > Your describing the commercially available BSDi operating system there. It already exists. >But I suspect that's what the merge with BSDi will produce. I hope >so, anyway. > No question that both products will benefit from the merger. Ted Mittelstaedt tedm@toybox.placo.com Author of: The FreeBSD Corporate Networker's Guide Book website: http://www.freebsd-corp-net-guide.com 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?010301c0ae3e$577a1d80$1401a8c0>