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

On Fri, Jun 11, 2010 at 11:10, Vincent Massol <vincent(a)massol.net> wrote: What would be great would be some kind of patch annotation a xwiki.org editor would just need to apply it by clicking on a button. We could also have the notion of "validated version", anyone can modify the document but a xwiki.org editor can validate a version. By default you view the last validated version but you can also see the last version if some modification has been made.

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