Re: Proposal to create multiple PHCs inside a top level /documenation folder

On 2010-05-20, Alex Clark <[email protected]> wrote:
> Hi,
>
> On 2010-05-20, Israel Saeta Pérez <[email protected]> wrote:
>> Plone Documentation is not a stalled nor a struggling project. 
>
> In your opinion.  mine, it is.

OOPS, A small bird in my ear has pointed out that this comment might be considered offensive 
to Israel (who must be given an enormous amount of credit for leading the doc team),
which was not my intention.

Israel, I apologize! :-)

I'm only voicing my own personal frustration with the current situation, and
trying to help. Anyway, carry on folks, and keep up the great work! :-)

>> We're 
>> making constant progress in several areas. I can say that documenting 
>> Plone 4 has been an important success, with only 2 PLIPs left (I'll have 
>> to lean on some people) and an User Manual with new Sunburst screenshots 
>> (something that requires a lot of mundane work). We're also preparing 
>> videos for the User Manual (which had not been updated since Plone 2) 
>> and an Installation Guide.
>
> That's great!
>
>> Most of our documentation will apply to both Plone 3 and 4 (and even 
>> 2.5). The parts only applying to Plone 4 have been marked appropriately, 
>> either as a whole like the Plone 4 User Manual, or specifically 
>> mentioning so in the associated paragraph. We are looking for special 
>> styles to tag version-specific stuff so it can be easily recognizable.
>
> Sounds good.
>
>> I'm very concerned with the split you're proposing. For the people 
>> writing documentation, this could mean duplicating (or more) the amount 
>> of work.
>>
>> We care about where the documentation is placed because we want the best 
>> for the project, and reduce the amount of unnecessary work. We're not 
>> just machines to throw a piece of code to document at. If we feel this 
>> is growing the wrong way and we can't get involved into the decisions 
>> because they correspond to the "website team", we'll become demoralized 
>> and just quit.
>
> OK
>
>> This wouldn't work, since current documentation applies to both Plone 3 
>> and Plone 4. As you can see, the process is not stalled. :)
>
> I don't see that. I don't see anyone (at least on this list) understanding
> the process but you and Anne. I could be wrong, of course.
>
>> If we copied and moved the documentation as you suggest, then if I 
>> wanted to document something present in both Plone 4.0 and 3.3.6, I 
>> would have to update the docs in both areas, which would mean double 
>> work. This is one of the strongest points I have against your proposal, 
>> and what makes me dismiss it now.
>
> Welcome to software and documentation.
>
>> If there are problems to identify which Plone version a certain document 
>> applies to, what we have to do is to improve how do we present this 
>> information visually, not to duplicate content and work.
>
> If you say so, I disagree, obviously.
>
>> It would be more effective to correct the giant mistake right away in a 
>> single doc, so the correction would be available immediately, instead of 
>> having to wait for the next release.
>
> Again, "effective" in your opinion.
>
>> I don't want you to see this as "stop energy". This would be like if you 
>> blamed the FWT for rejecting a PLIP which is not well-thought or too 
>> risky. I know you want the best for the documentation, but in this case 
>> the best, as Anne says, is to get the actual work done instead of 
>> performing unnecessary big changes.
>
> It would be hard for me to not see this as stop energy, TBH. Maybe others
> have a different perspective…
>
>> You can take a look at https://dev.plone.org/plone/report/8 and pick any 
>> task, or garden them.
>
> Right.
>
>>
>> -- israel
>>
>>
>> ------------------------------------------------------------------------------
>
>


-- 
Alex Clark · http://aclark.net
Author of Plone 3.3 Site Administration · http://aclark.net/plone-site-admin


------------------------------------------------------------------------------

_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs