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

On Mon, Jun 7, 2010 at 11:55, Sorin Burjan <sorin.burjan(a)xwiki.com> wrote: 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.

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