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

Hi,

My impression from the thread was the framework team aren't resisting
because they don't value documentation. They are resisting because the PHC
soup is too hard to "know well".

I think putting the responsibility back on the doc team or editors isn't the
answer. Even if we did have more people, editors can't possibly know the
implications of the code changes as well as those developing the new code.

If the docset is too hard to know then our job is to make it easy to know
and easy to change.
- Reduce the corpus down to a manageable size by splitting "official" from
community docs. Official being the only part PLIPS would require changing.
- Giving it a good table of contents so its very obvious which parts have
changed. PLIPs could reference chapters and sections.
- Removing all overlap so less needs to be changed. One place for everything
and everything in its place.
- Let developers easily integrate their existing module documentation if
appropriate in order to ease their load.
- the entire official docset appears multiple times on Plone.org, once for
each release and another for the upcoming (HEAD) version, so an author
doesn't have to consider old Plone versions in the writing itself.

Anything else we can do to make it easier for them?


Dylan Jay
Technical Solutions Manager, PretaWeb.com
---
M:+61421477460 ~ MSN:[email protected] ~ Y!+Skype:dylan_jay ~ ICQ:520341 

> -----Original Message-----
> From: JoAnna Springsteen [mailto:[email protected]]
> Sent: Monday, 1 December 2008 4:19 PM
> To: Israel Saeta Pérez
> Cc: Plone Docs List
> Subject: Re: [Plone-docs] [Framework-Team] Re: Fwd: Including
> aDocumentation 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=/
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs


-------------------------------------------------------------------------
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=/