On Fri, Jun 11, 2010 at 12:16, Vincent Massol <vinc...@massol.net> wrote: > > On Jun 11, 2010, at 12:00 PM, Thomas Mortagne wrote: > >> On Fri, Jun 11, 2010 at 11:39, Vincent Massol <vinc...@massol.net> wrote: >>> >>> On Jun 11, 2010, at 11:25 AM, Thomas Mortagne wrote: >>> >>>> On Fri, Jun 11, 2010 at 11:10, Vincent Massol <vinc...@massol.net> 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) >>>>> - 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"... > > Our code is also very anti wiki and it's code for a wiki... :) > Also a wiki doesn't mean it's open to everyone. It means it easy to > collaborate together *for people who have access to the wiki* of course ;) > > Now I agree with you it would be better to find a better solution such as the > one you proposed but between not doing anything and not improving our > documentation and improving our documentation practices I prefer to choose > the "improving our documentation practices" by far.
I don't see why it's everything or nothing. Having an open wiki does not makes it impossible to improve. > > 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: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 > -- Thomas Mortagne _______________________________________________ users mailing list users@xwiki.org http://lists.xwiki.org/mailman/listinfo/users
