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

On 05/20/2010 04:27 PM, Alex Clark wrote:
> Hi,
>
> Here is a re-print of the last section of my last email to the "longest doc team thread of all time".

I'd bet longest doc team thread of all time was the one started by Mikko 
some months ago.

> That thread has gotten a bit unwieldy, so I'd like to start a new convo based on the idea that
> we can create multiple PHCs inside a top level /documentation folder, to try to make
> everyone happy.
>
> (I would also like to trick Martin into reading this thread again ;-))
>
> This has several distinct advantages as far as I can tell:
>
> Gives immediacy
> ===============
> It creates a sense of immediacy for what (at least I, maybe others) perceive as
> a "stalled" project (or at least struggling project).


Plone Documentation is not a stalled nor a struggling project. 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.


> By immediacy, I mean that as soon as a 3.3.5 "tag" and and 3.3.6 and 4.0 branch
> are created, Israel, Anne, et al can continue to work in either 3.3.6 or 4.0,
> depending what they are working on (i.e. Plone 3 docs, or Plone 4 docs).
>
> Ends confusion
> ==============
> It completely eliminates the "what does this apply to?" problem. If something
> Plone 3 specific is found to be in a Plone 4 folder, we delete (or privatize) it
> because we know the same item exists in the Plone 3 folder, where it should be
> (or you clean it up for Plone 4, and leave the Plone 3 doc alone).


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.


> Lets things die
> ===============
> When 3.x.x and 4.x.x docs get too old (i.e. when it they are no longer supported
> by the community) we can privatize the folder. We have no way to kill things
> other than go through doc by doc and unmark something as 2.5 compatible, AFAICT.
 >
 >
> Anyway, here it is:
>
> ---
>
> Having beat the versioning drum to death, I would like to propose that the doc team let
> the "website team" split the documentation as suggested (effectively resulting in
> various branches and at least one tag).


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.


> I am starting to feel like that satisfies the most number of folks and has
> the least number of drawbacks:
>
> - current /documentation can be "frozen" in /documentation/release/3.3.5
> - Israel, Anne, et al can work in /documentation/develop/3.3.6
> - Israel, Anne, et al can work in /documentation/develop/4.0
> - Israel, Anne, et al can work in /documentation/develop/5.0
>
> If anyone cares, we can go backwards and create a /documentation/release/2.5.5
> that is a copy of 3.3.5, with all the content not marked 3 deleted.
>
> Thoughts?


This wouldn't work, since current documentation applies to both Plone 3 
and Plone 4. As you can see, the process is not stalled. :)

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.

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.

> [...]
> One last thing, if it is starting to feel like X.X.X is too may revisions of docs
> (which it was to me just now) consider this:
>
>      http://plone.org/documentation/release/2.5.x/kb/plone-with-apache/
>      http://plone.org/documentation/release/3.3.x/kb/plone-with-apache/
>
> This would not work, because if a giant mistake is found in 3.3.5/kb/plone-with-apache,
> it does not give the doc team any sane way to release newer 3.x docs (i.e. 3.3.6)
> because the next release in that scenario is 4.0.x. (Unless there were a 3.4)

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.


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.

You can take a look at https://dev.plone.org/plone/report/8 and pick any 
task, or garden them.

-- israel


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