Re: Proposal to manage documentation similar to (or along with) core software.

Hi,

On 2010-05-18, Israel Saeta Pérez <[email protected]> wrote:
> Sorry for replying late, but I've been busy and all.

No problem.

…

> In my opinion, your proposal is not just procedural but also structural. 
> Creating an area for 4.0 docs and putting docs there would mean that we 
> would have both the original doc and the one sitting in the 4.0 folder. 
> Whenever one wants to make an addition or correction valid for both 
> Plone 4 and 3, one would have to modify both documents.

No, one would not have to do that. That is basically the point of a release.
After the 4.0 docs get "released" you don't touch them. You can keep working 
on them, of course, somewhere else behind the scenes (We could use Plone! ;-)) 
and then when 4.1 comes out, you release your 4.1 docs.

And so on.

Also, the "site structure" of the website has absolutely nothing to do
with the Plone documentation IMO. The fact that the documentation team cares 
*this* much about how the documentation is presented on plone.org kind of 
surprises me. What if the FWT said "give us your documentation for the 4.0 
release" and you *had* to submit something? That totally eliminates the website 
from the equation.

Something to think about… ;-)

> Steve proposed to implement a traversal hack to display only docs tagged 
> for a certain version. For example, plone.org/documentation/4.x/ 
> displaying only docs for Plone 4. I would be entirely ok with this 
> approach, since it doesn't duplicate content and therefore doesn't 
> create a maintenance problem. It would place the 4.x in the URL so you 
> would experience a great warm/fuzzy feeling. ;)

I would, but then I'd know where the bodies were buried so the fuzzy
would go away. But seriously, that might be a fair compromise… if someone 
were willing to do the work (which I am not, I don't think). 

Also, what is this "maintenance problem" you keep referring to? :-) Let me rephrase 
that, can we agree, or at least be equally sensitive to the fact that not everyone is 
of the opinion that copying content == "maintenance problem"? :-D

> Regarding the stipend, I'm currently too busy with other jobs to be able 
> to allocate more time for this tasks, with or without money.

Which is fine. And the PF may or may not give it to you if you asked. I
mention it mostly just to mention it.

> John Schinnerer wrote:
>> In current plone documentation, it can be really hard to tell what
>> version(s) a given piece of documentation applies to. And, even when
>> there is a label that says what it applies to, maybe it applies to newer
>> versions and just hasn't been maintained. Or maybe it doesn't and hasn't
>> been maintained. Or there's no indication. Or there is an indication and
>> the indication is just plain wrong. Or it's out of date but there's no
>> way to tell without doing what the doc says and finding out it doesn't
>> work....and so on.
>
> We're working to keep manuals up-to-date and well tagged regarding the 
> version(s) they apply to. If you find any manual with incorrect/outdated 
> info, please open a ticket in the http://dev.plone.org/plone tracker, 
> documentation component, or mail me directly, and we will fix it.

But you wouldn't know, unless you knew. "Open a ticket if you find a 
mistake" only applies to a very small subset of folks (i.e. us). Everyone 
else going to /documentation expects to see… current documentation.

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