On Jun 11, 2010, at 12:21 PM, Thomas Mortagne wrote: > On Fri, Jun 11, 2010 at 12:16, Vincent Massol <[email protected]> wrote: >> >> On Jun 11, 2010, at 12:00 PM, Thomas Mortagne wrote: >> >>> 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"... >> >> 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.
As I said I care about only one thing: to improve the quality of the documentation: "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." Remember I was responding to Denis who was saying that we wasn't sure we should have such rules for xwiki.org because it would be more complex to contribute documentation. As I also said: "I'm also ok to have the new doc rules *and* have people act as wiki gardeners" 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: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 _______________________________________________ users mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/users
