Date: Sat, 07 Nov 1998 12:50:44 -0700 From: Chad David <davidc@acns.ab.ca> To: hackers@FreeBSD.ORG Subject: Re: freebsd-hackers-digest V4 #299 Message-ID: <3644A494.C40D3C8F@acns.ab.ca> References: <199811062019.MAA25886@hub.freebsd.org> <36449AA9.102BBB11@acns.ab.ca>
next in thread | previous in thread | raw e-mail | index | archive | help
> Date: Thu, 5 Nov 1998 16:03:02 -0500 (EST)
> From: Ryan Ziegler <ziggy@wopr.inetu.net>
> Subject: Re: Documentation upgrade: where are the other humans?
>
> lets move this to advocacy,
Before this thread dies here (I don't subscribe to advocacy) I would
like to volunteer. Over the past few months I can't count the times I
have wished for better documentation (LKM -> KLD would be nice).
Just when I finish writing something someone changes the interface,
or the library is upgraded. It's not as bad as Linux, but is was a little
depressing to joyfully congratulate myself for getting my first LKM
device driver to work, only to read five minutes later in Jordan's 3.0
announcement that LKM was dead.
>
>
> On Wed, 4 Nov 1998, Terry Lambert wrote:
>
> > > When not getting paid, programmers tend to code what they find
> > > interesting. We can say the same thing for writers when writing. I would
> > > say technical documentation is not the most exciting literary form, nor
> > > are the arguments for kmem_free() the most exciting subject matter.
>
I find the arguments for kmem_free() to be very exciting. A programmer is
only as good as the functions he can call. The idea that you can just learn
the
language and find the functions as you need them doesn't work very well if
there
are no docs for the functions you want or docs at least describing the
implementation.
If there were a man page for kmem_free() and any related calls it seems
unlikely the
discussion would have made it here.
> > >
> > > What we need are technical writers who feel a severe allegiance to
> > > FreeBSD.
> >
> > Or people who get off on techinical writing, or a professor with
> > an allegiance to FreeBSD in charge of a Technical Writing class.
> >
> > I have to say that there exist people who actually enjoy doing
> > things that the rest of us would find about as enjoyable as
> > home dentistry (those of you with capped teeth, imagine removing
> > your caps with an awl).
> >
> > I have a sister who happens to enjoy double-column bookkeeping.
> > It takes all kinds...
> >
> >
> > I also think that it's very likely that someone who had to take
> > a technical writing class for their CS/CIS/MIS/BIS degree would
> > have classmates who were English Majors or whatever, also looking
> > for writing projects, and that it would be a good idea to encourage
> > them suggesting FreeBSD documentation to their classmates as a
> > potential "project fodder gold mine".
> >
> > I know that if I were to adjunct teach a technical writing class,
> > I'd be please as punch if I could find a never-ending supply of
> > projects, all in the same general problem space; it'd make it a
> > hell of a lot easier to grade on a curve.
>
> Its more of a question of how many people who really enjoy home
> dentistry exist. Not many, simply isn't glamorous enough. What we need to
> do is to paint the technical writer as some sort of a hero or rogue. Give
> him a catchy name. "The dockers, a brand new breed of technical writers,
> infiltrating open source archives and documenting everything they see.
> They stop at nothing to see the cvs repositories of the world bloating up
> with inline documentation." Get an article on CNet and we're off.
>
> Approaching professors of technical writing classes doesn't seem like a
> bad idea, but those students have no allegiance to freebsd. We would
> easily wind up with inferior documentation (you can argue if thats better
> than no documentation at all).
> Maybe we could set up a synergy with the professor. The prof refers his
> students to us, they do what we want, and if we accept their work they get
> A's, otherwise, F's.
Point me at what needs to be documented. I am only one person, but
one person can make a huge difference to something like documentation
over a year.
>
>
> >
> >
> > > > Maybe it's just that the majority of people are too busy sitting
> > > > on their butts hacking code in cave-like computer labs to talk
> > > > to people in other departments on campus?
> > >
> > > You're not suggesting that we're a tad clannish, are you? :)
> >
> > Well, this *is* a "free software" project, not a "free product"
> > project... it's kind of self-limiting in its involvement of
> > people not that interested in producing software.
> >
> > The Linux Documentation project has that whole "Young Communist"
> > thing going for it...
Young Communist? "Coders of the world unite! You have nothing to
lose but the inability to figure out where the hell kmem_free() is actually
declared without resorting to find . -exec grep -l kmem_free {} \;!"
If you think about it OSS is largely a communist idea. "From each
according to his abilities, to each according to his needs". As long as
you can keep money out of the picture it will continue to work. Watch
out Linux.
I digress.
>
> I am still suprised to see that the microsoft vs good-software division
> hasn't erased the their-free-os vs our-free-os division. I also would
> think that with all the talk of OSS nowadays, people would be eager to
> latch onto the 'its not just linux and apache, its everyone' idea. Maybe
> they have, I don't know. Has freebsd tried to jump in the pool yet? Maybe,
> also, I make too many assumptions
>
> - -Ryan
>
> > Terry Lambert
> > terry@lambert.org
> > ---
> > Any opinions in this posting are my own and not those of my present
> > or previous employers.
> >
I apologize if this is not the place to volunteer, but I find that if you
want
to be heard this is the best place to talk. I also figured that it is at
least
as valid as the smoke signals and genetics threads :-).
Chad David
davidc@acns.ab.ca
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-hackers" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?3644A494.C40D3C8F>