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

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.

> 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