On Jun 11, 2010, at 11:10 AM, Vincent Massol wrote: > > On Jun 10, 2010, at 9:21 AM, Denis Gervalle wrote: > >> On Mon, Jun 7, 2010 at 11:55, Sorin Burjan <sorin.bur...@xwiki.com> wrote: >> >>> Hello. >>> >>> Silvia and me have created a DRAFT for XWiki.org Documentation Standard >>> found at : >>> http://dev.xwiki.org/xwiki/bin/view/Drafts/XWikiOrgDocumentationStandard >> >> >> Even if I found your procedures smart and very conscientious, I am a little >> bit afraid by them, and just wonder if these will not finally slow down the >> documentation, since only very minor change can be done quickly. As everyone >> knows, documentation is never what we d'like to do, and if you increase the >> burden, it will probably not encourage improvements. > > I haven't read the proposal yet, just answering to this part. > > Yes but we want a good quality for the documentation same as we want a good > quality for the code. What we did for the code is prevent anyone modifying it > by adding a notion of committer and people can still contribute patches which > are then reviewed by committers. Committers agree with the rules for ensuring > quality. > > The best solution IMO for having quality docs is to: > - close xwiki.org so that it's editable only to committers and people voted > as wiki editors (we need a process to get casual readers into wiki editors)
note that I didn't mean "voted" as in vote for the code. We can easily make it a lightweight process where it's enough for example to be sponsored by a xwiki committer without asking the others. -Vincent > - leave annotations/comments for people wanting to contribute small stuff > - allow anyone to access the Draft space > - make it very visible and easy how to contribute to xwiki.org (ie being > selected to be in the wiki editors group) > > 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:ou7hgdiiwgayghku+state:results >>> >>> >>> 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. _______________________________________________ users mailing list users@xwiki.org http://lists.xwiki.org/mailman/listinfo/users
