On Fri, Jun 11, 2010 at 11:39, Vincent Massol <[email protected]> wrote: > > On Jun 11, 2010, at 11:25 AM, Thomas Mortagne wrote: > >> On Fri, Jun 11, 2010 at 11:10, Vincent Massol <[email protected]> wrote: >>> >>> On Jun 10, 2010, at 9:21 AM, Denis Gervalle wrote: >>> >>>> On Mon, Jun 7, 2010 at 11:55, Sorin Burjan <[email protected]> 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) >>> - leave annotations/comments for people wanting to contribute small stuff >> >> 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. >> >>> - 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) >> >> 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. > > Sure but you're already talking about the next step which requires tooling > and is more complex to set up. I'd prefer to see step 1 done quickly and then > someone could work to do step2 as you mention. I've had this idea about > "validate version" since 2006 but it's still not there since someone needs > the time to implement it ;)
Step1 seems very anti wiki to me. Having to close that much our public wiki is not making it a good wiki example where we are saying to all clients that "wiki is great it makes everyone participate"... > > -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: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 > [email protected] > http://lists.xwiki.org/mailman/listinfo/users > -- Thomas Mortagne _______________________________________________ users mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/users
