From: Christian S. <chr...@da...> - 2007-02-17 17:37:40
|
Hey all, I finally found some time to read this novel of optilude and kind of understand it ;). I agree with most things, but to me it feels like the "What we are not doing" section is a bit too harsh and actually somewhat contradicts the goals we're going for: > - We should not go down any route that involve re-writing all the > documentation. I think no-one wanted to go down that route really... neither did anyone want to dump the existing docs and re-do them or have them re-submitted. > - We should not go down any route that requires in-depth editorial > review of every piece of documentation. We did that once, with a larger > team than this one and a quarter as many pieces of documentation, and it > took months just to get back to something which was as good as the what > we had before. That depends on what "in-depth editorial" means. I think some pieces of documentation that are in the doc area shouldn't really be out there at all, so I think that a somewhat stricter editing process wouldn't be a bad thing. > - We should not require every documentation author to re-do and > re-submit their work. We may choose to edit or retract some bad > documentation, and offer authors the chance to try again, but it is > unrealistic to expect people to have time to re-do documentation they > feel they've already given the community. This is doubly dangerous, > because it risks alienating the very people who's support we need. Again, I think no-one wanted to go that way. > - We should not segregate documentation so clearly that a large number > of people who've contributed documentation feels their efforts are > marginalised and thus not worth the effort. In a way you're asking for just that when you say you want some things to be in a trail (you referred to them as "blessed" docs at some point) and I think that's actually a good thing to do. > - We will not invent radically new technology. The PHC has taken years > to be complete, again mostly for lack of time, but it works reasonably > well. We can, and should, make incremental improvements to it, e.g. by > adding ratings. We will not introduce anything that will require complex > migration from the existing data structures. > ... > Perhaps we can engage with some of these at a later date, but for now, > we have more urgent needs that require more immediate attention, and > some grand adventure of documentation will get in our way. Again, no-one suggested rewriting PHC, but as you say yourself later, PHC will get extended and some changes can be incorporated along the way. This organic growth/evolution is a good thing, but we should seriously think about (and that's all we did) what an "ideal" doc-area would look like, just to be able to make sure that the PHC doesn't evolve into crap. We need a goal to aim for and collect and discuss ideas for that, after all Plone and therefore the need for good documentation is not very likely to die anytime soon, so having long-term plans can not be a bad thing. In the following "What we should do" section you say that imposing a certain structure on all existing documentation is out of the scope at this time. But what about the newly added and newly edited docs that will end up in the learning trails? Don't you think these could and should be best practice examples of how good Plone documentation should look? And I think you fail to see that the trails as being "our best idea" are the basis for all the other things that the we have discussed in the chat and on the wiki... organizing stuff in trails REQUIRES a certain structure for things that are in the trail, or you will end up with an incoherent, ill-structured mess with links. Joanna is on a very good way with the structural guideline and I'd be hard pressed to call this "arbitrarily decided"... she's a technical writer after all. > - Produce "trails" of documentation - > > :: Requires: 1 volunteer to document and promote the "trails" mechanism, > 1 volunteer to choose and structure a pilot "trail", and possibly others > to contribute to the trail. > > This is by far the best idea we've had, and the most concrete task. To > summarise, instead of aiming for perfection across all documentation, we > should pick up a few key topics that we reckon most members of a > particular audience would need to know. Examples may be "Connecting to > LDAP and other user sources" or "Developing new content types". This > "front-line" documentation should be thought through in more depth than > the rest of the how-tos and short tutorials. +10000 > I propose that we start with a single trail as a pilot. Whoever > volunteers for this gets to pick. A trail should be a Reference Manual > (we'll use the sections and audiences to ensure they end up on top, > possibly also a Smart Folder or template to show them more prominently). I'd like to pick up that one if no-one else has already (should we create a wiki-page for the responsibilities or are we having enough wikis already ;o). As for the subject I'll think about a couple of topics and propose them tomorrow evening in the doc chat. > The first step in defining a new trail is to work out the best learning > path for the intended audience and assess this against existing > documentation. From this, a workable structure of sections and > placeholder pages should be created. Some kind of gap analysis needs to > be completed to find out how the documentation we've got already matches > what we want. Then, one of four things may happen: > > (1) We link to existing how-tos and tutorials from a particular page in > the trail. There will probably be a short intro with context to save > users from having to browse through documentation that happens not to be > relevant to them. > > (2) We find existing documentation that's close, but not quite good > enough. We fix it up, possibly asking for help from the original authors > or experts in the community, and apply some pressure to make it happen > quickly. I guess this is will most often be the case. I'd really like to have stuff that enters the trails structured according to Joanna's style guide. Having sections as headers only is fine with me (but debatable for the future), and I guess that while trying to structure things that go into the trails we will find shortcommings of the guidelines and can fix them before others get to read them. > (3) We solicit new documentation, either by writing it ourselves or > asking something else nicely. Again, we prioritise this work and try to > reward people for producing something in days and weeks rather than months. > > (4) We leave that part of the trail blank. We can publish a trail that's > not yet fully complete if some nice-to-have sections are missing but > it's otherwise useful. Having clearly defined holes to fill help get > things completed. That's what I started the "Map" on openplans for a while back, to be able to collect topics that should be covered, and then organize them in a meaningful way and see where there are holes to fill. Toodles for now Christian |