[xwiki-users] [Proposal] Documentation Standard Document & Call to Vote
Hello. Silvia and me have created a DRAFT for XWiki.org Documentation Standard found at : http://dev.xwiki.org/xwiki/bin/view/Drafts/XWikiOrgDocumentationStandard 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:ou7hgdiiwgayg... 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) 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) 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.
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
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:ou7hgdiiwgayg...
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.
That would make sense only we we had a perfect documentation always updated which is currently not the case. There is lot's of missing stuff that someone will add at some point that will be true for old versions too.
c) We make the doc work the last 2 releases. That would be 2.3 and 2.4.
s/releases/branches/ d) What is done currently in many places is to indicate for a feature the version where it has been introduced, it does not make sense everywhere i guess but in some places it's very useful.
Note: If option b) is chosen then we need to add a step to the release process. (export for every release)
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.
+1 for a) i doubt we can do b). BTW I'm pretty sure we already talked about that not so long ago.
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)
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.
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
Hello, I think the most important is to have an up to date documentation, so I favour minimalist options * (the fewer the better)*. Q1 : I vote for option b) but this is not conflicting with d) proposed by Thomas. Q2 : Option a) the default skin. A comment regarding this draft : I'm not sure that the USERS mailing list is appropriate to ask for a documentation change. The documentation is a component of the XWiki software and it must match the features implemented. So, for me, the DEV mailing list would be quite natural.
On Tue, Jun 8, 2010 at 11:20, GeLo <[email protected]> wrote:
Hello,
I think the most important is to have an up to date documentation, so I favour minimalist options * (the fewer the better)*.
Q1 : I vote for option b) but this is not conflicting with d) proposed by Thomas.
Q2 : Option a) the default skin.
A comment regarding this draft : I'm not sure that the USERS mailing list is appropriate to ask for a documentation change. The documentation is a component of the XWiki software and it must match the features implemented. So, for me, the DEV mailing list would be quite natural.
Actually you answered on USERS only but the proposal has been sent on both USERS and DEVS ;)
_______________________________________________ users mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/users
-- Thomas Mortagne
Just to point out that my comment is focused on the "Documentation Standard" draft, not the current mailing thread. Following the document, if you want to update a page or create a new one, you have to "ask the XWiki community before starting". Below this sentence, the "user mailing list" is clearly specified. Maxime 2010/6/8 Thomas Mortagne <[email protected]>
Actually you answered on USERS only but the proposal has been sent on both USERS and DEVS ;)
-- Thomas Mortagne _______________________________________________ users mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/users
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. 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:ou7hgdiiwgayg...
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.
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
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 - 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) 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:ou7hgdiiwgayg...
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.
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.
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:ou7hgdiiwgayg...
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
On Jun 11, 2010, at 11:10 AM, Vincent Massol 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)
note that I didn't mean "voted" as in vote for the code. We can easily make it a lightweight process where it's enough for example to be sponsored by a xwiki committer without asking the others. -Vincent
- leave annotations/comments for people wanting to contribute small stuff - 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)
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:ou7hgdiiwgayg...
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.
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 ;) -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:ou7hgdiiwgayg...
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.
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:ou7hgdiiwgayg...
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
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. 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:ou7hgdiiwgayg...
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.
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.
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:ou7hgdiiwgayg... > > > 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
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:ou7hgdiiwgayg... >> >> >> 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
On Fri, Jun 11, 2010 at 12:25, Vincent Massol <[email protected]> wrote:
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.
Maybe this is a too short summary of what I have said. But truly, my point was that if everyone (committers or good contributors) has too go to the draft space and get some community agreement to publish their draft in the documentation, this will increase the burden so much that I may just leave it as is. I completely understand the needs of improving the documentation. Your proposal to close the wiki, and use comments/annotations is not so bad, compare to the current proposed procedures. Like Thomas, I just feel that this is not the wiki way, like using the draft space like proposed is neither the wiki way. IMO, the proposal of Thomas is exactly the way to go, and is part of the improvement I was suggesting initially, I means to have the ability to have a previous version of a document as the current one. I think that wiki is great but sometime publish new/changed stuffs too quickly, the preview state is too short and restricted to a single user, we need a larger preview ! Using the draft space is not practical IMO. Since this need should not be unique, improving the ability of XWiki to manage drafts could be a very good investment.
As I also said: "I'm also ok to have the new doc rules *and* have people act as wiki gardeners"
Since I have not a large experience of the current documentation, I have some question now: is the gardening task so hard currently ? what are finally the goals of introducing these procedures ? Could not this wait till we have the above feature ? Denis
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:ou7hgdiiwgayg... >>> >>> >>> 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
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
On Jun 11, 2010, at 1:46 PM, Denis Gervalle wrote:
On Fri, Jun 11, 2010 at 12:25, Vincent Massol <[email protected]> wrote:
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.
Maybe this is a too short summary of what I have said. But truly, my point was that if everyone (committers or good contributors) has too go to the draft space and get some community agreement to publish their draft in the documentation, this will increase the burden so much that I may just leave it as is.
I completely understand the needs of improving the documentation. Your proposal to close the wiki, and use comments/annotations is not so bad, compare to the current proposed procedures. Like Thomas, I just feel that this is not the wiki way, like using the draft space like proposed is neither the wiki way. IMO, the proposal of Thomas is exactly the way to go, and is part of the improvement I was suggesting initially, I means to have the ability to have a previous version of a document as the current one. I think that wiki is great but sometime publish new/changed stuffs too quickly, the preview state is too short and restricted to a single user, we need a larger preview ! Using the draft space is not practical IMO. Since this need should not be unique, improving the ability of XWiki to manage drafts could be a very good investment.
As I also said: "I'm also ok to have the new doc rules *and* have people act as wiki gardeners"
Since I have not a large experience of the current documentation, I have some question now: is the gardening task so hard currently ? what are finally the goals of introducing these procedures ? Could not this wait till we have the above feature ?
We will never have these features if nobody works on them. As I said I have been dreaming about them since 2006 and they're nowhere started :) What we do need: 1- make the wiki easier to use globally. This means implementing the new xwiki org design done by Silvia/caty (http://incubator.myxwiki.org/xwiki/bin/view/Improvements/XWikiOrgv2). Silvia sent a mail asking for help implementing it but nobody has volunteered so far. The first step could be to implement the horizontal navigation. 2- add more documentation for missing topics 3- improve existing documentation (for example by explaining when a feature has been added, refresh screenshots with newer versions, etc) 4- reorganize content (aka wiki gardening) But this is all very different from what Silvia/Sorin were proposing. They're just proposing a good code of conduct for contributing to xwiki.org and this is no brainer IMO. The only discussion is about specific items which may take too much time to abide by when adding doc but this needs to be reviewed one by one (and again I haven't read the proposal yet... ;)). Anyway let's stop this parallel thread for now and focus on the proposed proposal! Thanks -Vincent PS: But we still need to find volunteers for item 1 above...
Denis
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:ou7hgdiiwgayg... >>>> >>>> >>>> 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.
participants (5)
-
Denis Gervalle -
GeLo -
Sorin Burjan -
Thomas Mortagne -
Vincent Massol