Re: [Framework-Team] Re: Fwd: Including a Documentation section in each PLIP

> What would work/be enough for you? I'd love to make a decision and commit to
> it in the next documentation editor's meeting.
>

It would be handy if specific docs could be linked to from the PLIP so
we know which docs need to be updated. Searching for them may or may
not be tricky, depending how well you know the doc set. *shrugs*
Mostly it just takes a little time. Some people may not be willing to
invest that time when submitting a PLIP. But that makes me wonder if a
PLIP is really taking the bigger picture into consideration if the
person filling it out doesn't care to worry about docs it may affect.
A PLIP may be a good idea but if we don't look at the bigger picture
and see how it fits, how do we know if it's something we should
include? Is it too much to ask that the person submitting the PLIP
expands their view of the bigger picture to include docs as well? Does
it really set the submission bar too high? I honestly don't know. I
suspect that's something the Framework team needs to think about.

Biggest thing that would need to happen is have devs/framework team
work more closely together.

It's easy to update docs when we have a list of features/PLIPs. Once
the doc team has that list, we can comb through the docs and pick out
which ones need to be updated. It worked fairly nicely for us when we
updated docs for the Plone 3 release. Having that is enough for us to
get by. But I'd like to see us update docs every time the
functionality is changed. I'd really love to see everything documented
as it's developed. And by documented, I don't just mean comments in
the code. I'd love to see API, how tos/tutorials/manuals, doc
tests/user stories, and anything else that might help us. (Yes, I am
an idealist, but hey if we're talking wish list here, why not.)

This is a really tough call. Right now we don't have enough people
actively volunteering and doing work on the doc team to handle this on
our own. The success of this idea, like many others, depends on people
getting in there and getting it done. Even if the editorial team
agrees to try and take this on, that doesn't guarantee us man power to
do it.

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/