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

Hi,

On 2010-05-20, Dylan Jay <[email protected]> wrote:
> I actually think versioning by major version is enough
>
> e.g. documentation/manuals/plone4/developer
> documentation/manuals/plone3/developer

Then how would you stage content? If you create:

    http://plone.org/documentation/develop/3.0
    http://plone.org/documentation/release/3.0

and:

    http://plone.org/documentation/develop/4.0
    http://plone.org/documentation/release/4.0

Once you release 3 and 4 (which you only do once, and don't touch after), you'd have 
to wait until 5 before you could publish (aka release) again.

As far as I can tell, this amounts to shooting the doc team in the foot ;-)
At least with:

    http://plone.org/documentation/develop/3.3.5
    http://plone.org/documentation/release/3.3.5

and:

    http://plone.org/documentation/develop/4.0
    http://plone.org/documentation/release/4.0

You could create a:

    http://plone.org/documentation/develop/3.3.6

and:

    http://plone.org/documentation/develop/4.1

as soon as:

    http://plone.org/documentation/release/3.3.5
    http://plone.org/documentation/release/4.0

go out the door.

Hell, you could even release a 3.3.6 of the documentation
sans a Plone 3.3.6 (as long as we declare that it's the
documentation that *would* have been release had 3.3.6
been released).

Anyone know if there is a 3.3.6 in the works?

Alex

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


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