Hi Anne!
Post by Anne BowtellOK, 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).
Post by Anne BowtellWith 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)
Post by Anne BowtellWell, 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".
Post by Anne BowtellAnd, 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.
Post by Anne BowtellBut 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 ;-)
Post by Anne BowtellI'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/)
Post by Anne BowtellWe 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 ;-)
Post by Anne BowtellIf 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".
Post by Anne BowtellThanks
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
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