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

I actually think versioning by major version is enough

e.g. documentation/manuals/plone4/developer
documentation/manuals/plone3/developer


On 20/05/2010, at 9:45 AM, Alex Clark wrote:

> Hi Anne!
>
> On 2010-05-19, Anne Bowtell <[email protected]> wrote:
>> OK, that's fine going forward, but what about the Plone 3  
>> documentation.
>
> Let it die. Unless there is a 3.3.6, in which case I'd release  
> whatever documentation
> has changed since you released the 3.3.5 documentation. Note:
>
> - Of course, there are no "3.3.5 docs" right now. But you could take  
> the existing
>  set of "Plone 3 docs" and release them as the "3.3.5. docs" If  
> there are things
>  in that set of docs that don't apply to 3.2 or 3.1 or 3.0, then so  
> be it. I'm
>  not sure I'd worry about that at this point.
>
> - If you were to do that, then you'd continue edit the 3.3.5 docs in  
> private until
>  such time as 3.3.6 comes out (if it comes out).
>
>> 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.
>
> See above, the short answer is "don't worry about it." (IMO)
>
>> 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.
>
> Any time is the time for big plans IMO, but I hear you. To be honest,
> I'm not so sure it would be *that* bad to release the current set of
> documentation as the 3.3.5 documentation, and keep developing the 4.0
> documentation "in private" until such time as it is ready. This is
> open source, so people will get it when they get it. (IMO)
>
> Remember, no one really knows what you guys are doing (IMVHO). I'm  
> trying to
> bridge the gap between the hard work that is occuring, and the
> perception of the general public which is "confusing docs".
>
>> 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.
>
> No, I understand you are concerned about that, *within* your  
> documentation.
> What I don't understand is why you care *where* your documentation
> is placed on the website, e.g.:
>
> /documentation/
>
> vs.
>
> /documentation/3.3.5
> /documentation/4.0
>
> And so on.
>
>> 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.
>
> Not quite. I'm asking that folks consider my proposal to "version"
> documentation. Period. And a postcript: I'm also asking that they be
> continually be aware (in the background, so to speak) that I formally
> asked the PF for money to fund the documentation effort, in case it's
> ever needed, or desired in the future.
>
> That said, in terms of *actual* work you have to do, everything
> I am proposing could probably be done outside the scope
> of the documentation team's efforts, whatever they are. Perhaps
> that is where the confusion is occuring.
>
> There are at least two other teams peripherally involved:
>
> - FWT
> - Website team
>
> But also:
>
> - Evangelism
> - Marketing
>
> (Are these different?)
>
> In short, *everyone* that does Plone is at least "loosely" concerned
> about the public-facing documentation.
>
> Of all these folks, which is everyone basically :-), it is probably  
> safe
> to say that *none* of them would want to discourage the documentation
> team in any way from doing what it is doing. That is not at all what
> this is about. In fact, just the opposite. I think everyone  
> appreciates
> that we have such dedicated folks.
>
> What this is about is "framing" and "clarifying" and "tranparency-i- 
> fying"
> our documentation team's efforts. I could login to plone.org right now
> and rename /documentation to /3.3.5, and create a /documentation  
> folder
> (not help center) and move /3.3.5 to it to create /documentation/ 
> 3.3.5.
>
> Once 3.3.5 is created, we could further split it into:
>
> /documentation/release/3.3.5
> /documentation/develop/3.3.6
> /documentation/develop/4.0
>
> So, at this point, 3.3.5 would not get touched. 3.3.6 would get fixes
> to 3.3.5 and 4.0 would receive the full 4.0 treatment.
>
> When 4.1 approaches, you repeat the process.
>
> I am willing to do a great many things to assist in making this
> happen. I only mentioned not being willing to work on a traversal
> hack because I don't fully understand how that would work. I
> suspect it won't work the way I want it to ;-)
>
>> 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.
>
> Yeah, I got questions in my class like "is all this stuff going to
> be anywhere but in PP3 or your PSA book?" and I had to give them my  
> generic
> answer: there is great stuff on plone.org if you know where to find
> it (e.g. a search for apache gives you
> http://plone.org/documentation/kb/plone-with-apache/)
>
>> 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.
>
> Hmmm, well that is a fair point. But I am just trying to prevent  
> "stop energy".
> When I hear things like "I don't want to duplicate content" my stop  
> energy
> bell goes off ;-)
>
>> 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.
>
> Heh. If you guys let me rename the PHCs and such on plone.org, I'll  
> start writing
> docs (and fixing tickets :-).
>
> Seriously, my book is wrapping up soon, and I very much hope to have  
> more time to
> devote to documentation "proper".
>
>>
>> Thanks
>>
>> Anne
>>
>>
>>
>> --------------030400080905070405060401
>> Content-Type: text/x-vcard; charset=utf-8;
>> name="anne_bowtell.vcf"
>> Content-Transfer-Encoding: base64
>> Content-Disposition: attachment;
>> filename="anne_bowtell.vcf"
>>
>> YmVnaW46dmNhcmQNCmZuOkFubmUgQm93dGVsbA0KbjpCb3d0ZWxsO0FubmUNCmVtYWlsO2lu
>> dGVybmV0OmFubmUuYm93dGVsbEBtZWRzY2kub3guYWMudWsNCnRlbDt3b3JrOis0NCAoMCkx
>> ODY1IDg4MjgyOQ0KeC1tb3ppbGxhLWh0bWw6RkFMU0UNCnZlcnNpb246Mi4xDQplbmQ6dmNh
>> cmQNCg0K
>> --------------030400080905070405060401
>> Content-Type: text/plain; charset="us-ascii"
>> MIME-Version: 1.0
>> Content-Transfer-Encoding: 7bit
>> Content-Disposition: inline
>>
>> ------------------------------------------------------------------------------
>>
>>
>> --------------030400080905070405060401
>> Content-Type: text/plain; charset="us-ascii"
>> MIME-Version: 1.0
>> Content-Transfer-Encoding: 7bit
>> Content-Disposition: inline
>>
>> _______________________________________________
>> Plone-docs mailing list
>> [email protected]
>> https://lists.sourceforge.net/lists/listinfo/plone-docs
>>
>> --------------030400080905070405060401--
>>
>>
>
>
> -- 
> 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


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