Re: [xwiki-users] [xwiki-devs] [Proposal] Documentation Standard Document & Call to Vote

On Fri, Jun 11, 2010 at 12:25, Vincent Massol <vincent(a)massol.net> wrote: Maybe this is a too short summary of what I have said. But truly, my point was that if everyone (committers or good contributors) has too go to the draft space and get some community agreement to publish their draft in the documentation, this will increase the burden so much that I may just leave it as is. I completely understand the needs of improving the documentation. Your proposal to close the wiki, and use comments/annotations is not so bad, compare to the current proposed procedures. Like Thomas, I just feel that this is not the wiki way, like using the draft space like proposed is neither the wiki way. IMO, the proposal of Thomas is exactly the way to go, and is part of the improvement I was suggesting initially, I means to have the ability to have a previous version of a document as the current one. I think that wiki is great but sometime publish new/changed stuffs too quickly, the preview state is too short and restricted to a single user, we need a larger preview ! Using the draft space is not practical IMO. Since this need should not be unique, improving the ability of XWiki to manage drafts could be a very good investment. Since I have not a large experience of the current documentation, I have some question now: is the gardening task so hard currently ? what are finally the goals of introducing these procedures ? Could not this wait till we have the above feature ?

Denis > > Thanks > -Vincent > >>> Also if you count how many people contribute to the wiki you'll see some > interesting statistics.... >>> >>> I'm also ok to have the new doc rules *and* have people act as wiki > gardeners. One problem is that we have no way to reach how to someone to > educate him on how he should add documentation on the wiki except by fixing > his mistakes and hoping he'll see someone has changed it. >>> >>> I'm open to all solutions except for the ones that say: we don't want to > improve the quality of the documentation. IMO quality goes through > consistency and consistency is achieved with design and barring that with > rules. >>> >>> Now I(we) need to review the doc proposed by Silvia and Sorin and see > see if for each rule there's an automated way of enforcing it by design > (like a form, etc) or not. But I know not all rules are enforceable by > design easily so we'll need rules anyway. >>> >>> Thanks >>> -Vincent >>> >>>>>>> I don't see other solutions. If we leave it open then it'll > committers/wiki editors who will have to fix what people contribute which is > a pain after a few times. >>>>>>> >>>>>>> WDYT? >>>>>>> >>>>>>> Thanks >>>>>>> -Vincent >>>>>>> >>>>>>>> My idea is that there >>>>>>>> should be an additional intermediate editing situation, where you > improve or >>>>>>>> add a section in the current documentation directly without going > to a draft >>>>>>>> and review cycle (almost like when you fix a issue without vote > when you >>>>>>>> know what to do). You could also add precision when you read the >>>>>>>> documentation and have failed to catch it, to avoid the next one to > also >>>>>>>> have the same trouble. >>>>>>>> I have the impression that we loose the wiki nature of the > collaboration by >>>>>>>> using these procedures.... >>>>>>>> >>>>>>>> ... and this could be a larger reflexion on the feature of XWiki > since such >>>>>>>> situation is not uncommon. I have already some idea about that, but > I had >>>>>>>> never have time enough to write them in details. Briefly, IMO we > should >>>>>>>> offer a feature that allows a document to have its current version > not the >>>>>>>> latest one, until the author of the latest version confirm his > desire to >>>>>>>> publish their changes. As you said, we never want to see unbacked > bread, and >>>>>>>> this is why, in some situation, direct publication is not > appropriate. I >>>>>>>> will not say more here since this is clearly another thread.... >>>>>>>> >>>>>>>> >>>>>>>>> >>>>>>>>> >>>>>>>>> In order to move towards the final version, we need your input on > 2 issues. >>>>>>>>> - For which project version we create & maintain documentation >>>>>>>>> - Which skins we are going to support in the documentation > (latest/all) >>>>>>>>> >>>>>>>>> Although, these issues were discussed in December 2009, no final > result >>>>>>>>> came out of them. >>>>>>>>> >>>>>>>>> > http://markmail.org/message/ou7hgdiiwgayghku#query:+page:1+mid:ou7hgdiiwgay… >>>>>>>>> >>>>>>>>> >>>>>>>>> 1. the project version (XE version for ex) for which the > documentation >>>>>>>>> is created/updated/maintained. >>>>>>>>> We have several choices: >>>>>>>>> a) We make the documentation only for the latest version. >>>>>>>>> b) We make the documentation only for the latest version, and > we >>>>>>>>> export the pages at release time and make it available as a zipped > HTML >>>>>>>>> export so that people using the older version can refer to > them. >>>>>>>>> c) We make the doc work the last 2 releases. That would be 2.3 > and >>>>>>>>> 2.4. >>>>>>>>> >>>>>>>>> Note: If option b) is chosen then we need to add a step to the >>>>>>>>> release process. (export for every release) >>>>>>>>> >>>>>>>> >>>>>>>> For me b) is not an option, documentation is not written / updated > on >>>>>>>> release day, but before it, when the features are released in the > Mx and RCx >>>>>>>> versions. Since we start Mx of next release before release of > previous one, >>>>>>>> we cannot managed such versioning easily. >>>>>>>> For now, to stay reasonable, I think we should do as we do in > source code, >>>>>>>> and mention the version were a feature is introduced or changed > when >>>>>>>> confusion should be avoided. >>>>>>>> >>>>>>>> >>>>>>>>> 2. The skin used for documenting steps. This also includes the > screenshots. >>>>>>>>> Again we have several choices: >>>>>>>>> a) Document only for the latest default skin. >>>>>>>>> b) Document for all supported skins. Right now that would be > Toucan >>>>>>>>> + Colibri (not sure about Albatross, I don't think we've > officially said >>>>>>>>> it wasn't supported). >>>>>>>>> >>>>>>>>> Note: If option b) is chosen, this would mean 2 screenshots for > the >>>>>>>>> same feature (one for each skin) >>>>>>>>> >>>>>>>> >>>>>>>> I doubt we could do b), reaching a correct a) is already an issue > when the >>>>>>>> default skin is upgraded. >>>>>>>> >>>>>>>> Denis >>>>>>>> >>>>>>>> >>>>>>>>> The vote content was mostly taken from the markmail link above. >>>>>>>>> >>>>>>>>> >>>>>>>>> If you have any other suggestions regarding this draft, please > reply and >>>>>>>>> state your opinion. We need as much feedback as possible in order > to >>>>>>>>> create a solid documentation standard.