Re: New unofficial document - oamp.pdf

[Mark Farquaad <markfarquaad@gmail.com>]

ATTENTION:
This is another long post with *details* of what I am trying
to commuincate.
If short on time OR not interested in the FAQ / documentation,
IGNORE AND DON'T READ THIS message!
You have now been warned Windows-style!

Mark
;-)


On Sat, 1 Jan 2005 13:53:49 -0500, Sunny Raspet <slr@mordac.info> wrote:
> Most of this thread has been answered quite well by Nick and the other
> people who chimed in.  Though the whole thing is clearly trollish or
> stupid (pick one, depending on how charitable you're feeling)

Why, thank you!
And a good day to you too!
If it's just stupid or trollish, why answer?
Try to be a little more fair if you don't agree on someone
else's opinion, o.k.?

> Despite what many people think, good documentation is not "easy".  Good
> documentation does not come quickly.  Good documentation is not
> something created in five minutes by passersby.

Agreed.
But putting further hurdles and rocks into the path of someone
willing to contribute, just to "test" his "overall will" to endure
abuse in order to be "allowed" to contribute his free time for 
free doesn't help the situation. Believe me.
Some of these hurdles and rocks might be put there intentionally,
which I disagree with, but most are probably there coincidentally.
And that might be changed, if there were a will to do so.


> Without trying to pick on the efforts of the people at
> openbsdsupport.org, when you look at documentation created by committee,
> that's an excellent example.  There is no editing for style, content, or
> grammar/spelling.  There is no fact-checking.  There is no good basic
> reference material; there are only "recipes" for stuff that *might*
> work.  Then again, it might not.  

Agreed *AGAIN*. (Just to use capitals for once in the favor 
of my "opposition"... :-)
You are right. 100%, there's no denying it!

But is that all a reason to permanently and 100% shut it out
from any improvement process of the official documentation?
Why not take in all efforts and see what you (and all volunteers) 
can do together with the existing?
Why not create an official documentation project where people
can submit that kind of stuff, then create a structure or form
of organization where such work can be worked on by others?

Eventually it *MIGHT* ripen to something which is in the end
worthy of including in the FAQ / documentation!

I'm not saying to include all (or even any) of the existing work
of openbsdsupport.org the way it is now, but why not stretch
out a hand from the *official* OpenBSD project and team to
people willing to invest their time for free to help others with
openBSD??

Because OpenBSD doesn't care to support anything which
doesn't benefit security of the OS???

How do you know it won't??
How do you know, if OpenBSD creates a documentation project, 
a virtual meeting room and creative lab where texts, drafts, works 
in progress etc. can be stored and worked uppon by a larger 
number of volunteers, won't eventually produce good quality 
stuff that, in the sense of OpenBSD devs and Theo,
is worthwhile of including in the FAQ / docu?

If you don't try, you don't know!
I for one am not participating with openbsdsupport.org,
becuase it seems clear, nothing, no matter what good work
you put into it, will ever be included in the official OpenBSD
FAQ / docu.

Yes, let's take me for instance, it seems a popular topic:
I could help out at least with correcting english of some
people, who technically know much much more than me
and who are capabable of writing technical correct docu.
But, sadly, because OpenBSD does not offer a documentation
project, this won't ever happen.
The guy who doesn't write good english but knows the tech stuff
doesn't write his docu, becuase he knows his english is
too bad.
And I, who can get away with halfway understandable english,
don't help bring his docu up to english expectations, becuase
it's not submitted, not part of the official OpenBSD, will never
be written in the first place and even then, is copyrighted by
its author who wants to get at least a *little* credit if he is not
allowed to make his free time and effort part of the OS he'd
like to contribute and help with.
And the same goes with fact checking, grammer, etc., etc.

Look, isn't it opvious we agree that writing good docu
is a very big task?
Why not agree that it's too big to be done by one guy allone?

Does one guy allone write the entire source code?
No! It's an ongoing effort of many people!

Then why not split the work needed for good docu,
editing, grammar checking, checking for facts, technical
correctnes, etc., etc., upon many people also???
Why not let those who can speak good english do 
the grammar checking, let those who know facts do
the fact checking, etc.?
Why not let many people work on one single little document
instead of as today, require one person to be a pro in all those
fields required for good docu?
All that does is cancel the possible good work of 500 people
and leaving only one, (if any at all!) who has ALL capabilities
at the same time, the will, and the time to do so.
No wonder noone contributes the the FAQ!

There is big difference here between code (patches) and
documentation:
With code, you can do it as is done with docu and code today:
You can expect people to write an entire patch for a little
piece of code, which is correct in all aspects and manners 
and works.

With documentation it's not that easy! Even on one little page
of documentation, maybe even just one sentence, you need 
to be able to split the work among those people who are capable
of doing the required tasks, grammer, spelling, tech, fact checking,
etc.
And this in term is only possible if you create a repository of works
in progress which is publicly available and where anyone (basically)
can try work on something stored there or waiting for improvement.
Of  course things would have to be coordinated somehow,
I havn't thought about that too much yet, but it's pointless to
do so if there is no interest in any such new approach on creating 
documentation.


> And the footer of the page actively
> discourages (to my mind) the help of editors.

YES!
Every copyright does. That's why it should all be part of
the official openBSD project and all in its "possession", 
but free to work on for anyone willing to improve on the 
OpenBSD docu.

> And yes, I said talent.  While it's nice to think in kindergarden terms
> of "everyone has something to contribute" and "everyone can help"... the
> simple fact is, everyone *can't*.  Any documentation, for instance, that
> you wrote?  From your style in these emails, Mark, I am guessing that it
> would require more editing than it was worth.

If there are people willing to do editing, editing ceases to pose
a problem. But you must offer the opportunity and possiblity
for texts to be submitted and available for editing first.


> That said, Nick, being a generous person, is willing to work with people
> in the hopes that they will get better.  I've made exactly one
> reasonably decent contribution to the FAQ; the section on CARP.  I don't
> really want to think about how long it took him to edit it, considering
> the changes.  And I have written professionally (in fact, the piece is a
> re-work of one of my published articles).
> I seem to remember (though this could be my brain acting up) that
> someone connected with the project has publically stated that some new
> developers require more time than they're strictly worth.  

Yes! This is a (or the!?) problem!
That's what I'm trying to change with my new / different approach
to the entire documentation process (only FAQ, NOT man pages!).
And I need the pooled effort and brain power of all here to make this
idea all it could be worth. - If at all.


> And yet there
> are new developers all the time.  The same goes for the FAQ.  Nick has
> no problem helping people out and answering their questions about how to
> contribute, even if he could do it himself in less time.  He does,
> however, require that some small minimum of effort be shown[1].  Once
> that's there, he's the nicest editor/Guy in Charge that I've ever worked
> with.  ;)

Yes, you're absolutely right again!! *sight!*
This is all part of the problem I am trying to address with
my (seemingly radical because completely new and unknown)
different approch to creation of documentation!


> The people that CAN write and ARE worth the time and DO have the time?
> They will contribute, and they will not be "scared off" by a list of
> guidelines.  They will, in fact, appreciate them very much.  I wish said
> guidelines been written before I submitted my piece; I might have been
> able to spare Nick some time.  As it stands, when I get time to write
> more content (and that's coming, if slowly), I will take advantage of
> them.

Way to go!
I'm not saying Nick's guidelines are worthles.
Not in the very least!
They are probably invaluable!
Still, at the current time in the non-existing support of OpenBSD for
texts in progress, they potentially scare off people who might want
to contribute. I'm not saying throw away Nick's guidelines at all!
I'm saying build everything else around them to make em
be as valuable and much-used as they could be.

Imagine a project as I envision, where people can do smaller pieces
of work on texts, knowing even if it's a little contribution, it will count
and help, there Nick's guidelines would surely be invaluable.
All I want is to split up work more.
And I believe it's possible, if only the infrastructure (web page,
mailing list (ok. ok... you *DON'T* like discussion boards.. *sight* ;),
repository, guidelines etc., would exist!

In such a project one could split up work on what needs to be done
to a certain text still, such as editing, spellchecking, technical
checking, etc. and then Nick might have an entire staff he trusts,
who does the final checking for him. They don't do the correcting,
ONLY the checking!


> It's that simple.

No. It's not simple at all!
I strongly disagree!
Simple doesn't cut it here in my oppinion.


> [1]: And writing stupid, rambling emails to misc@ does not count as
> "effort", per se.

O.K. someone pleaded me to write shorter posts...
It's not that easy! There's a whole bunch of stuff I need to 
communicate and I can't do that in short posts which might
or might not fit your particular current timely allowance.
I urge people who are not themselves directly involved in 
the FAQ or strongly interested to ignore me and my posts.

I am trying to write as short as possible, but this is a first
time for me too! And you must agree it's doesn't look like
I was very successful sofar in describing what this is all
about. Least not by the seemingly still very small true
understanding here on this list of what I want or rather am
trying to propose.

You can't ask for details and then complain about too
too long posts...(!)

Greetings,
Mark