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

Hi all,

On 2010-05-17, Dylan Jay <[email protected]> wrote:
> On 17/05/2010, at 11:44 PM, David Hostetler wrote:
> What we're really talking about versioning here is something like http://collective-docs.plone.org/
> which still has holes but is far less piecemeal than the documentation  
> knowledge base (http://plone.org/documentation/kb).

I think that we are all talking about different things, to some extent, but that this
has been, and continues to be a great thought/planning exercise.

Personally, after "going hard" at Plone for the past 5 years or so, I am starting
to take a look around and I see an awesome, but still "rough" project. My goal is to 
"polish" the project from the top down, starting from within my area of expertise i.e. 
systems and reaching out to other areas like the framework team and doc team as "needed" ;-)

So back to docs, I have no doubt the doc team can, and does produce awesome 
documentation. I also have no doubts about what the Plone community can accomplish 
if/when it sets its mind to something. Given that what I'm proposing for the doc team 
to do is largely procedural, I coupled my suggestions with a pitch to the PF to fund some 
of the work, in a way modeled after the über-successful framework team.

In fact, an easy way to think of what I am after is if you were suddenly
to make the "release manager" responsible for releasing documentation
in addition to software. What would that look like? It'd mean that in the
case of Plone 4.0, Eric Steele would suddenly have more work to do and would 
probably investigate having me killed ;-)

But seriously. I picture that looking like a number of things
we've discussed i.e. versioning the documentation. But also, maybe
bundling documentation with the software a la Silva (if you
install the Silva CMS, you can add a "docs" folder to the
site, or something like that).

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

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

But that could just be me. :-)

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