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

On 12/2/08 12:42 AM, Dylan Jay wrote:
>> -----Original Message-----
>> From: Wichert Akkerman [mailto:[email protected]] On Behalf Of
>> Wichert Akkerman
>> Sent: Tuesday, 2 December 2008 5:49 AM
>> To: Dylan Jay
>> Cc: 'JoAnna Springsteen'; 'Israel Saeta Pérez'; 'Plone Docs List'
>> Subject: Re: [Plone-docs] [Framework-Team] Re: Fwd: Including
>> aDocumentation section in each PLIP
>>
>> Previously Dylan Jay wrote:
>>      
>>> 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 don't think there's been any discussion on it actually. But indeed, I
>> do not think it is reasonably to ask PLIP implementers to find all
>> relevant entries in PHC.
>>      
>
> That was my take on the framework team discussion. That developers updating
> the actual Plone.org documentation is too hard and even linking to the docs
> which should be updated is pretty hard.
>
>    
>> What I want from PLIP implementers is the following:
>>
>> - a description of what changes for developers (ie new patterns to use)
>> - a description of what changes for users (ie new patterns to use)
>> - proper documentation for new features.
>>
>> All or none of those may be doctests, as long as they are readable
>> documentation, not tests with some narrative in between code snippets.
>>
>> That should give the documentation more than enough data to find and
>> update documetation on plone.org
>>      
>
> I think this would be a great improvement but this means it's the doc teams
> job to update the documentation which I think is what is currently broken in
> this process and will result in an overloaded doc team and docs not done.
>
> Why not go one further and say if the developer is changing the api by
> creating or changing core modules its also their job to directly alter the
> api/developer documentation. User documentation is still probably better
> done by the doc team.
>    

I do not think we can require that until that API documentation is 
managed in a developer-friendly way. For me as developer that means 
preferable inside the package(s) itself, but definitely in a svn-managed 
location in restructured text format. If you force me to edit webpages 
using kupu I will most likely never get around to it.

> 6.5) doc team editor is now part of the PLIP review process and reviews the
> developer documentation changes to see if they are acceptable
>    

The review process has no special roles. If the doc team wants someone 
to be part of the review process they will have to volunteer to be a 
member of the framework team, just like we have Danny doing user 
interface review as part of the framework team.

Wichert.

-- 
Wichert Akkerman<[email protected]>    It is simple to make things.
http://www.wiggy.net/                  It is hard to make things simple.

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