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

Sorry for replying late, but I've been busy and all.

On 05/18/2010 12:09 AM, Alex Clark wrote:
> Dahoste is right in that "versioned docs" means nothing unless
> there are docs to version. But it's not putting the cart before
> the horse to talk about versioning. It's simply a procedural
> step in which you declare "I am going to create a documentation 'release'".
> What happens after that point, I referred to as "working towards a release".
>
> To me, that work means these steps:
>
> - Create an area of the site for "4.0 docs"
>
> - Put manuals, faqs, whatever in there.
>      - installation manual
>      - end user manual
>      - developer manual
>      - pictures of limi in his lotus

^^ Probably the most interesting part of the documentation. :P


> - Work on the docs
>
> - "Release" the docs (that means stop working on the docs ;-))
>
> - Repeat for 4.x and 5.x et al
>
> And that's basically it.
>
> Thanks for listening, all!
>
> Alex
>
> P.S. I'm also a bit skeptical of the doc team's "But I don't to create duplicate content" position.
> If the goal were to not duplicate content, then I'd agree my proposal would be "bad".
> But isn't the goal to produce and maintain the highest quality documentation for Plone
> releases? "We" (i.e. the doc team) are already doing that to a large degree. What I am
> proposing is largely procedural. You could even make the arg it has nothing to do
> with the doc team (i.e. it borders on the website team's domain, to some extent).
> What are the *real* CONS to "duplicate" (but clearly separated) documentation, other
> than offending personal preference?
>
> It's like I said in a previous email, I don't view avoiding duplicate documentation
> as any kind of "win", given the status quo.


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.

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. ;)

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.


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.

-- israel


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