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

On 2010-05-19, Dylan Jay <[email protected]> wrote:
> 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.

+1. There should be *zero* pushback from the documentation team on 
Sphinx generated documentation IMO. Let's just find a way to 
assemble our collective efforts in a sane way, whatever they/that may be.

/documentation kicks ass, it just needs help,
collective-docs kicks ass, it just needs acceptance :-)

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

Indeed, let me ask you this. Would you be happy if a 3.3.6 and 4.0
PHC existed on plone.org to house collective-docs (in the way 
you guys setup)?

This would achieve versioning, more or less.

I imagine you would manage branches, tags and trunks yourselves
in the collective, and then when 4.0 (e.g.) got released on 
plone.org you would *stop* updating that PHC ;-)

In this way, I believe you are right, people would go to 

    http://plone.org/documentation/4.0/developer-manual
    (or http://plone.org/documentation/4.0/collective-developer-manual ? do we have two of them?)

and see that their contributions to the collective ending up on plone.org and
get excited ;-)

That may be a gateway to joining the "real" docs team (for lack of a better
way to put it, and no offense intended, of course :-)).

Alex


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


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