Re: [Plone-docs] Re: Let's knock it up a notch

[JoAnna S. <jl...@gm...>]

   Friday   16:30-20:30 GMT+2
   Saturday 16:30-20:30 GMT+2

I can do saturday pretty much all day. I'd like to think I'm
converting this correctly (yes I looked it up) but if I'm not in
#plone at said time, feel free to shoot me an email.

> >> I think the most important thing is getting some co-ordination. If Pau=
l
> >> is
> >> interested in taking on this role, I'd be pleased.

I'll second Paul. I'll help too but he seems to have a better idea of
what needs to be done.


> I agree - short version is better. Some comments:
>
> "We assume that people have read the Plone Book (aka. Definitive Guide to
> Plone) - so trivial things should not be documented here." ... this book
> is actually out of date. To be honest, I'm not sure this test has been
> applied at all. What do people think? Do we require some minium standard
> of knowledge or not?

Minimum standard of knowledge would be great but expecting someone to
read, understand, and apply all the content in the guide is going to
really limit the audience of who can help.


from a previous email (I'm working backwards here):
>2) Review

>a. Make sure the artifact still is correct for Plone 2.1.2.

>b. Rate and assign topics.

>c. Improve language, fix typos, etc.

* I'll volunteer for this one as this is where my expertise lies.


>d. Goal is quantity of reviewed artifacts, not quality of the review.
>At this stage, anything more than 20 min per review is diminishing returns=
.

* I kind of disagree here... Quality is the important part. Lack of
quality documentation is one of Plone's biggest fault. It make the
tool inaccessible to potential new users. Yes we need to get through a
lot of documents in a day, but lets make sure these are quality
documents. Otherwise we're just saving more work for a later point in
time that may or may not come.
I like Martin's idea of using a tracker. Perhaps we can categorize
docs by how much effort is going to be needed to edit the piece?


>Plone is written a product, but often used as a framework. Unfortunately,
>internal documentation and development practices have always focused on th=
e
>former, not the latter. That means that e.g. API documentation and consist=
ency
>is a problem. We need to address that, but I don't think we could reasonab=
ly
>document all the current API without also refactoring it all (I'd love for=
 you
>to prove me wrong)

You know we could tackle this with what he had talked about months and
months ago...pairing up a documentor and a programmer and document as
you develop. This is more of a long term goal and something that we
could integrate into the development process. Keeping the
documentation and the programming together as one package could ensure
that each time a new release comes around that it comes with up to
date documentation.


Some of my thoughts:
One of my personal concerns is the way some of the documents are
written. Now please do not be offended by what I'm about to say...but
it's pretty obvious that developers are doing a lot of the writing.
(ok obvious to me but that's because I'm a writer by training)
I would really like to do some serious in depth editing of a lot of
the documents so that we can address things like tone, active voice,
grammar, punctuation, and really just make sure that they adhere to
basic technical documentation principles. (ie: write to the lowest
common denominator...which is not always possible but you can write
with a specific audience in mind, and when doing so remember that
we're not all programmers)  :) So after saying this, I will gladly
take this on in the future. This is your open invitation to write
something and send it to me for editing. Do it any time you are
getting ready to publish something.

Ok that's all for now!
Can't wait to do some documenting!
J.