Date: Sat, 17 Mar 2001 06:48:40 +1000 (EST) From: Doug Young <dougy@bryden.apana.org.au> To: Ted Mittelstaedt <tedm@toybox.placo.com> Cc: richard childers <fscked@pacbell.net>, 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: <Pine.BSF.4.21.0103170632520.1458-100000@bryden.apana.org.au> In-Reply-To: <010301c0ae3e$577a1d80$1401a8c0@tedm.placo.com>
next in thread | previous in thread | raw e-mail | index | archive | help
A major problem with developers writing documentation is that (for whatever reason) they invariably aim it at people of their own level .... waaaaaaayyyyy over the heads of regular users. The people running the majority of the "user-friendly" resource sites wouldn't have nearly as much knowledge as the developers .... to my mind the contribution they make deserves far greater recognition by the FreeBSD core team than appears to be the case. I've received hundreds of complimentary emails over the past year from newbies about my "Pedantic FreeBSD" ... undoubtedly the owners of freebsddiary / bsdvault / etc have received infinitely more. I wonder how many compliments the FreeBSD docs team receive ?? ..... I for one would be EXTREMELY surprised if any !!!! It is possible to developers to write halfway intelligible docs ... Brian Somers doesn't appear to have a problem with it but unfortunately the majority of the others certainly do. On Fri, 16 Mar 2001, Ted Mittelstaedt wrote: > >-----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 > 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?Pine.BSF.4.21.0103170632520.1458-100000>