11 Jun
2010
11 Jun
'10
12:16 p.m.
On Jun 11, 2010, at 12:00 PM, Thomas Mortagne wrote:
On Fri, Jun 11, 2010 at 11:39, Vincent Massol
<vincent(a)massol.net> wrote:
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.
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
On Jun 11, 2010, at 11:25 AM, Thomas Mortagne wrote:
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"... On Fri, Jun 11, 2010 at 11:10, Vincent Massol
<vincent(a)massol.net> wrote:
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 ;)
On Jun 10, 2010, at 9:21 AM, Denis Gervalle wrote:
> On Mon, Jun 7, 2010 at 11:55, Sorin Burjan <sorin.burjan(a)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. >>> 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:ou7hgdiiwgay…
>>>>>
>>>>>
>>>>> 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.