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

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