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

>
>> 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.
>    
OK, that's fine going forward, but what about the Plone 3 documentation. 
With respect to the theme reference manual - it does not yet document 
everything that's required for Plone 3 theming. So is that just 
abandoned, half-finished? There are plenty of people around still using 
Plone 3.
> 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.
Well, it's because we're aware of what needs to be done, the size of the 
task ahead of us, how thin on the ground and, to a certain extent, 
de-moralized the documentation 'team' is, how unfinished the current 
projects are, and how much we're relying on one person (Israel) to hold 
it all together at the moment. Just making big plans when what we need 
to do is get our heads down and work out how to get the Plone 4 
documentation required done (and all the boring, mundane tasks like 
screenshots that that required) is taking a great deal of energy. This 
isn't really the time for big plans.

And, I can tell you, that trying to organize and structure the manual 
that I put together was tough but also really important. I'm sort of 
surprised that you should think that we wouldn't be concerned about 
presentation and structure.
> 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
>    
But the people who have to do the work of maintaining the documentation, 
*are* of that opinion. You mention in the previous paragraph, that 
you're not willing to engage in a task or commit to a course of action  
that you feel isn't appropriate - which is fair enough. But that's what 
you're asking us to do.

I'm demoralized enough as it is, but I have to say that yesterday I 
spent the whole morning helping a colleague who wanted to build his 
first content type and I simply couldn't find the information he needed 
on plone.org (although I'm sure its buried there somewhere) - so I've 
been writing it all up on my own website. It made no difference whether 
this was Plone 4 or 4.1 - in actual fact it was Plone 3 - whatever he 
did would have been pretty much relevant to both. The information he 
needed just wasn't discoverable and not delivered in a format that 
helped him, as an integrator, complete the task that he had to do. 
That's the bigger picture and the bigger problem.

We all want a more polished Plone, but the reality is that there 
fundamental things to do in building a community of documentors who 
actually write documentation for end users, integrators and developers. 
Who maybe have experience in these all these roles or have experience in 
helping people in these roles. There's room for blue-skies thinking of 
course, but I just don't think that right now this discussion is helping 
us much.

If everyone who's been involved in the discussion could commit to 
completing at least two documentation tickets over the weekend and 
encouraging someone new to join into the documentation process by 
dealing with a ticket, then perhaps we'd be in a position to move forward.

Thanks

Anne

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

_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs

begin:vcard
fn:Anne Bowtell
n:Bowtell;Anne
email;internet:[email protected]
tel;work:+44 (0)1865 882829
x-mozilla-html:FALSE
version:2.1
end:vcard