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

I can really hear the pain here and see the demoralisation. There is  
so much work to do and not enough people to do it.

but let me just put this out there. If no one else new is  
contributing, what is the reason why?

Perhaps the current process isn't working for them and so they are  
turned off.

The #1 problem with plone is developer documentation rather than user  
manual documentation. We have Mikko which has put a huge amount of  
effort into a new developer manual which I think is now more useful  
than the current developer manual. He did it in sphinx because it has  
a documentation process more familiar to developers. Lots of others  
have expressed their desire to document Plone this way. Yet there has  
been continued resistance to making the collective developer manual  
official. So we're stuck with a documentation process that isn't  
attracting anyone new and telling a whole bunch of developers they  
can't document unless they do that using that old way.

I know I sound like a broken record on this subject. It's not because  
I'm trying to be a smart arse, or trying to be right or anything. It's  
because I honestly honestly believe this will work. We'll get more  
developers documenting Plone in a more controlled fashion. It will be  
easy to version and therefore make more readers trust it. The more  
developers actually start relying on a single developer manual the  
more they will want to contribute. It's a virtuous circle. Give it a  
try. Pleeeeeeeeeaaaaaasssssssseeeeeeeee :)


On 19/05/2010, at 6:39 PM, Anne Bowtell wrote:

>>
>>> 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
>
>
> < 
> anne_bowtell 
> .vcf 
> > 
> ------------------------------------------------------------------------------
>
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs


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