This month is DOC month - I'll take a lead.
XTeam: I hope you don't mind me giving you a name. :-) Sort of like the "A-Team". I hope it gives you a sense of pride. You are working on one very important software system. Why? Because Xwiki answers certain to needs that no other wiki does. In this respect, it is trully a unique system that has both great capability now and extraordinary promise for the future. A few noteworthy facts: Siebel Systems is using XWiki. Siebel is a worldwide leader in customer relationship management systems. More than one team at IBM leverages XWiki. IBM is a world leader in software, hardware, and business consulting services. XWiki has even taken life inside of the corporate offices of UPS, the worlds largest package delivery company. Give yourselves a big pat on the back! But not too big; I need your help. I have only recently joined the "XTeam" and my first goal is to fill a task that many do not often enjoy - creating and editing documentation. I do not necessarily enjoy writing documents, but I know that the importance of good documentation is too often overlooked. I believe that good documentation will help the evolution of XWiki more potently than most realize. I believe that... People judge XWiki before even trying it based soley on the quality of the documentation. First impressions are critical. If administrators have a poor installation experience (due to poor docs, for example), they will be disenchanted immediately. Innovative developers who can bring powerful enhancements to XWiki can bring those improvements faster if we decrease the initial learning curve through solid documentation. Open source projects are typically poor in documentation. Thus, we can look at this as a lesson and strive to use this as a point of great differentiation. My goal over the coming month is to play a strong role in transforming the User Guide and Administrator Guide. To achieve this goal, I pledge to work on documentation a little bit each day. Afterwards, I will probably roll into the usability and user interface focus. Until then, i hope you will accept me as a workhorse for you. Here's how you can help me (and the XWiki evolution): 1. Take a little time out to reflect on some things you have learned about XWiki and document them in the new guide areas. DEV GUIDE: http://www.xwiki.org/xwiki/bin/view/DevGuide/WebHome ADMIN GUIDE: http://www.xwiki.org/xwiki/bin/view/AdminGuide/WebHome 2. Feel free to send rough notes, comments, or thoughts to me and I will do the dirty work of cleaning them up and finding an adequate home for them in the guides, 3. Explore the organization of the new guides. Look for empty holes. Ask yourself what you might be able to contribute there and contribute something if you can. I am sure that before the month is over, we may reorganize the guides more than once just to get them "just right", so expect to see some changes and some movement of documents. Ludovic has already gotten a reorg started; it isn't perfect, but it is better. Progress must be iterative. Expect frequent questions from me here as I struggle to learn and ensure accuracy of the documentation. At a minimum, please remember that source code documentation can be extremely valuable for other XTeam members. Otherwise, just keep up the great work on the software and do what you can to review and improve the accuracy of the new docs that will be going up over the month (as time permits). ================================== Cody Burleson [email protected]
Great !! We have introduced daily "15mn documentation" rule here in Paris... The results of this are: * a refactored Linux/Tomcat/MySQL install page http://www.xwiki.org/xwiki/bin/view/AdminGuide/Linux+Tomcat+MySQL * The addition of the xwikilinks table in the Database Schema page (feature will be released in the next version) * The start of the usability section on http://www.xwiki.org/xwiki/bin/view/Usability/WebHome Ludovic Cody Burleson wrote:
XTeam:
I hope you don't mind me giving you a name. :-) Sort of like the "A-Team". I hope it gives you a sense of pride. You are working on one very important software system. Why? Because Xwiki answers certain to needs that no other wiki does. In this respect, it is trully a unique system that has both great capability now and extraordinary promise for the future.
A few noteworthy facts:
* Siebel Systems is using XWiki. Siebel is a worldwide leader in customer relationship management systems. * More than one team at IBM leverages XWiki. IBM is a world leader in software, hardware, and business consulting services. * XWiki has even taken life inside of the corporate offices of UPS, the worlds largest package delivery company.
Give yourselves a big pat on the back! But not too big; I need your help.
I have only recently joined the "XTeam" and my first goal is to fill a task that many do not often enjoy - creating and editing documentation. I do not necessarily enjoy writing documents, but I know that the importance of good documentation is too often overlooked. I believe that good documentation will help the evolution of XWiki more potently than most realize.
I believe that...
* People judge XWiki before even trying it based soley on the quality of the documentation. * First impressions are critical. If administrators have a poor installation experience (due to poor docs, for example), they will be disenchanted immediately. * Innovative developers who can bring powerful enhancements to XWiki can bring those improvements faster if we decrease the initial learning curve through solid documentation. * Open source projects are typically poor in documentation. Thus, we can look at this as a lesson and strive to use this as a point of great differentiation.
My goal over the coming month is to play a strong role in transforming the User Guide and Administrator Guide. To achieve this goal, I pledge to work on documentation a little bit each day. Afterwards, I will probably roll into the usability and user interface focus. Until then, i hope you will accept me as a workhorse for you. Here's how you can help me (and the XWiki evolution):
1. Take a little time out to reflect on some things you have learned about XWiki and document them in the new guide areas.
DEV GUIDE: http://www.xwiki.org/xwiki/bin/view/DevGuide/WebHome ADMIN GUIDE: http://www.xwiki.org/xwiki/bin/view/AdminGuide/WebHome
2. Feel free to send rough notes, comments, or thoughts to me and I will do the dirty work of cleaning them up and finding an adequate home for them in the guides,
3. Explore the organization of the new guides. Look for empty holes. Ask yourself what you might be able to contribute there and contribute something if you can.
I am sure that before the month is over, we may reorganize the guides more than once just to get them "just right", so expect to see some changes and some movement of documents. Ludovic has already gotten a reorg started; it isn't perfect, but it is better. Progress must be iterative. Expect frequent questions from me here as I struggle to learn and ensure accuracy of the documentation. At a minimum, please remember that source code documentation can be extremely valuable for other XTeam members. Otherwise, just keep up the great work on the software and do what you can to review and improve the accuracy of the new docs that will be going up over the month (as time permits).
================================== Cody Burleson [email protected]
------------------------------------------------------------------------
-- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
-- Ludovic Dubost XPertNet: http://www.xpertnet.fr/ Blog: http://www.ludovic.org/blog/ XWiki: http://www.xwiki.com Skype: ldubost AIM: nvludo Yahoo: ludovic
Cody, We've started to implement xwiki at my company, and the documentation is the biggest gripe that we have had so far. We've only been using it for about a month so far -- not much experience, but the "pains" that we have gone through are still fresh in my head. Let me know if there is anything else I can do to help out other than what was listed in your email -- I'd be happy to help, and I'm sure I can find a few more people around the office to pitch in as well. Vern On 9/11/05, Cody Burleson <[email protected]> wrote:
XTeam:
I hope you don't mind me giving you a name. :-) Sort of like the "A-Team". I hope it gives you a sense of pride. You are working on one very important software system. Why? Because Xwiki answers certain to needs that no other wiki does. In this respect, it is trully a unique system that has both great capability now and extraordinary promise for the future.
A few noteworthy facts:
Siebel Systems is using XWiki. Siebel is a worldwide leader in customer relationship management systems. More than one team at IBM leverages XWiki. IBM is a world leader in software, hardware, and business consulting services. XWiki has even taken life inside of the corporate offices of UPS, the worlds largest package delivery company. Give yourselves a big pat on the back! But not too big; I need your help.
I have only recently joined the "XTeam" and my first goal is to fill a task that many do not often enjoy - creating and editing documentation. I do not necessarily enjoy writing documents, but I know that the importance of good documentation is too often overlooked. I believe that good documentation will help the evolution of XWiki more potently than most realize.
I believe that...
People judge XWiki before even trying it based soley on the quality of the documentation. First impressions are critical. If administrators have a poor installation experience (due to poor docs, for example), they will be disenchanted immediately. Innovative developers who can bring powerful enhancements to XWiki can bring those improvements faster if we decrease the initial learning curve through solid documentation. Open source projects are typically poor in documentation. Thus, we can look at this as a lesson and strive to use this as a point of great differentiation. My goal over the coming month is to play a strong role in transforming the User Guide and Administrator Guide. To achieve this goal, I pledge to work on documentation a little bit each day. Afterwards, I will probably roll into the usability and user interface focus. Until then, i hope you will accept me as a workhorse for you. Here's how you can help me (and the XWiki evolution):
1. Take a little time out to reflect on some things you have learned about XWiki and document them in the new guide areas.
DEV GUIDE: http://www.xwiki.org/xwiki/bin/view/DevGuide/WebHome ADMIN GUIDE: http://www.xwiki.org/xwiki/bin/view/AdminGuide/WebHome
2. Feel free to send rough notes, comments, or thoughts to me and I will do the dirty work of cleaning them up and finding an adequate home for them in the guides,
3. Explore the organization of the new guides. Look for empty holes. Ask yourself what you might be able to contribute there and contribute something if you can.
I am sure that before the month is over, we may reorganize the guides more than once just to get them "just right", so expect to see some changes and some movement of documents. Ludovic has already gotten a reorg started; it isn't perfect, but it is better. Progress must be iterative. Expect frequent questions from me here as I struggle to learn and ensure accuracy of the documentation. At a minimum, please remember that source code documentation can be extremely valuable for other XTeam members. Otherwise, just keep up the great work on the software and do what you can to review and improve the accuracy of the new docs that will be going up over the month (as time permits).
================================== Cody Burleson [email protected]
-- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
Fantastic ! I love the XTeam monicker and admire the lead you are taking in the documentation effort. Thumbs up to Cody ! -- Luis Arias http://www.xwiki.com http://www.innover-entreprendre.net skype : kaaloo +33 6 14 20 87 93 mobile
Cody, It's great to see some focus on XWiki documentation. Thanks for taking the lead on this. Since XWiki is constantly evolving, one of the challenges of documenting it is the "moving target" phenomenon. Say you document the XWiki permissions UI. Then a new version is released, and the permissions UI changes. For a time (perhaps a very long time), the documentation is out of sync with the current released version. This will cause end-user confusion and frustration, and it's an example of how out-of-date documentation can be worse than no documentation at all. Other examples include users running old versions of XWiki, looking at a documentation page that describes how a particular feature works in the current released version, and experiencing confusion. To help address these challenges, I suggest affixing a message at the top of each documentation page, like this: For XWiki version: 0.9.840+ As new versions of XWiki are released, the documentation team can review each documentation page and determine whether the material is out of date. If the new version differs substantially in its behavior, the message could be changed to: For XWiki version: 0.9.840 - 0.9.970 where 0.9.970 is the last version that the page accurately documents. This will help readers to know whether the page accurately documents the version of XWiki they're using. Eventually, the page will be revised to reflect the new functionality, but users running old versions of the XWiki software still need a way to view the documentation for their version. To deal with this, the documentation could provide a link to to the older version of the page. Something like this: For XWiki version: 0.9.975 See also: <link>XWiki 0.9.840 - 0.9.970</link> Thoughts? Stephen
From: Cody Burleson <[email protected]> Reply-To: [email protected] To: [email protected] Subject: [xwiki-dev] This month is DOC month - I'll take a lead. Date: Mon, 12 Sep 2005 00:45:26 -0400
[snip]
My goal over the coming month is to play a strong role in transforming the User Guide and Administrator Guide. To achieve this goal, I pledge to work on documentation a little bit each day. Afterwards, I will probably roll into the usability and user interface focus. Until then, i hope you will accept me as a workhorse for you. Here's how you can help me (and the XWiki evolution):
I think this is a good suggestion. What might be better is to us text like: Verified on XWiki versions: 0.9.840 That way, if others confirm it for a new version, they can just add that version to the list. Also - some people would not know whether it works on one version over another because they may only be familiar with one version. In this way, the wiki approach to information sharing, validation, etc. might be used to good effect. ================================== Cody Burleson IBM, Business Consulting Services On Demand Workplaces "Simplifying access to content, applications, people and processes." Current Client Office (Mon - Thur): (404) 828-4583 Home Office [Friday, Sat. Sun. or email a voice message]: (214) 233.3546 Cell [anytime]: (214) 537-8783 Email: [email protected] "Stephen Schaub" <[email protected]> 09/27/2005 03:07 PM Please respond to [email protected] To [email protected] cc Subject RE: [xwiki-dev] This month is DOC month Cody, It's great to see some focus on XWiki documentation. Thanks for taking the lead on this. Since XWiki is constantly evolving, one of the challenges of documenting it is the "moving target" phenomenon. Say you document the XWiki permissions UI. Then a new version is released, and the permissions UI changes. For a time (perhaps a very long time), the documentation is out of sync with the current released version. This will cause end-user confusion and frustration, and it's an example of how out-of-date documentation can be worse than no documentation at all. Other examples include users running old versions of XWiki, looking at a documentation page that describes how a particular feature works in the current released version, and experiencing confusion. To help address these challenges, I suggest affixing a message at the top of each documentation page, like this: For XWiki version: 0.9.840+ As new versions of XWiki are released, the documentation team can review each documentation page and determine whether the material is out of date. If the new version differs substantially in its behavior, the message could be changed to: For XWiki version: 0.9.840 - 0.9.970 where 0.9.970 is the last version that the page accurately documents. This will help readers to know whether the page accurately documents the version of XWiki they're using. Eventually, the page will be revised to reflect the new functionality, but users running old versions of the XWiki software still need a way to view the documentation for their version. To deal with this, the documentation could provide a link to to the older version of the page. Something like this: For XWiki version: 0.9.975 See also: <link>XWiki 0.9.840 - 0.9.970</link> Thoughts? Stephen
From: Cody Burleson <[email protected]> Reply-To: [email protected] To: [email protected] Subject: [xwiki-dev] This month is DOC month - I'll take a lead. Date: Mon, 12 Sep 2005 00:45:26 -0400
[snip]
My goal over the coming month is to play a strong role in transforming the User Guide and Administrator Guide. To achieve this goal, I pledge to work on documentation a little bit each day. Afterwards, I will probably roll into the usability and user interface focus. Until then, i hope you will accept me as a workhorse for you. Here's how you can help me (and the XWiki evolution):
-- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
We could use the tag system for this.. Using tags version-0.9.840 we could detect tags which start with "version-" and indeed show a "Verified on XWiki version: " text at the end of the page.. Ludovic Cody Burleson wrote:
I think this is a good suggestion. What might be better is to us text like:
Verified on XWiki versions: 0.9.840
That way, if others confirm it for a new version, they can just add that version to the list. Also - some people would not know whether it works on one version over another because they may only be familiar with one version. In this way, the wiki approach to information sharing, validation, etc. might be used to good effect.
================================== Cody Burleson IBM, Business Consulting Services On Demand Workplaces "Simplifying access to content, applications, people and processes."
Current Client Office (Mon - Thur): (404) 828-4583 Home Office [Friday, Sat. Sun. or email a voice message]: (214) 233.3546 Cell [anytime]: (214) 537-8783 Email: [email protected]
*"Stephen Schaub" <[email protected]>*
09/27/2005 03:07 PM Please respond to [email protected]
To [email protected] cc
Subject RE: [xwiki-dev] This month is DOC month
Cody,
It's great to see some focus on XWiki documentation. Thanks for taking the lead on this.
Since XWiki is constantly evolving, one of the challenges of documenting it is the "moving target" phenomenon. Say you document the XWiki permissions UI. Then a new version is released, and the permissions UI changes. For a time (perhaps a very long time), the documentation is out of sync with the current released version. This will cause end-user confusion and frustration, and it's an example of how out-of-date documentation can be worse than no documentation at all. Other examples include users running old versions of XWiki, looking at a documentation page that describes how a particular feature works in the current released version, and experiencing confusion.
To help address these challenges, I suggest affixing a message at the top of each documentation page, like this:
For XWiki version: 0.9.840+
As new versions of XWiki are released, the documentation team can review each documentation page and determine whether the material is out of date. If the new version differs substantially in its behavior, the message could be changed to:
For XWiki version: 0.9.840 - 0.9.970
where 0.9.970 is the last version that the page accurately documents. This will help readers to know whether the page accurately documents the version of XWiki they're using.
Eventually, the page will be revised to reflect the new functionality, but users running old versions of the XWiki software still need a way to view the documentation for their version. To deal with this, the documentation could provide a link to to the older version of the page. Something like this:
For XWiki version: 0.9.975 See also: <link>XWiki 0.9.840 - 0.9.970</link>
Thoughts?
Stephen
From: Cody Burleson <[email protected]> Reply-To: [email protected] To: [email protected] Subject: [xwiki-dev] This month is DOC month - I'll take a lead. Date: Mon, 12 Sep 2005 00:45:26 -0400
[snip]
My goal over the coming month is to play a strong role in transforming the User Guide and Administrator Guide. To achieve this goal, I pledge to work on documentation a little bit each day. Afterwards, I will probably roll into the usability and user interface focus. Until then, i hope you will accept me as a workhorse for you. Here's how you can help me (and the XWiki evolution):
-- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
------------------------------------------------------------------------
-- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
-- Ludovic Dubost XPertNet: http://www.xpertnet.fr/ Blog: http://www.ludovic.org/blog/ XWiki: http://www.xwiki.com Skype: ldubost AIM: nvludo Yahoo: ludovic
That is an even better idea. ================================== Cody Burleson IBM, Business Consulting Services On Demand Workplaces "Simplifying access to content, applications, people and processes." Current Client Office (Mon - Thur): (404) 828-4583 Home Office [Friday, Sat. Sun. or email a voice message]: (214) 233.3546 Cell [anytime]: (214) 537-8783 Email: [email protected] Ludovic Dubost <[email protected]> 09/27/2005 04:50 PM Please respond to [email protected] To [email protected] cc Subject Re: [xwiki-dev] This month is DOC month We could use the tag system for this.. Using tags version-0.9.840 we could detect tags which start with "version-" and indeed show a "Verified on XWiki version: " text at the end of the page.. Ludovic Cody Burleson wrote:
I think this is a good suggestion. What might be better is to us text like:
Verified on XWiki versions: 0.9.840
That way, if others confirm it for a new version, they can just add that version to the list. Also - some people would not know whether it works on one version over another because they may only be familiar with one version. In this way, the wiki approach to information sharing, validation, etc. might be used to good effect.
================================== Cody Burleson IBM, Business Consulting Services On Demand Workplaces "Simplifying access to content, applications, people and processes."
Current Client Office (Mon - Thur): (404) 828-4583 Home Office [Friday, Sat. Sun. or email a voice message]: (214) 233.3546 Cell [anytime]: (214) 537-8783 Email: [email protected]
*"Stephen Schaub" <[email protected]>*
09/27/2005 03:07 PM Please respond to [email protected]
To [email protected] cc
Subject RE: [xwiki-dev] This month is DOC month
Cody,
It's great to see some focus on XWiki documentation. Thanks for taking the lead on this.
Since XWiki is constantly evolving, one of the challenges of documenting it is the "moving target" phenomenon. Say you document the XWiki
permissions
UI. Then a new version is released, and the permissions UI changes. For a time (perhaps a very long time), the documentation is out of sync with the current released version. This will cause end-user confusion and frustration, and it's an example of how out-of-date documentation can be worse than no documentation at all. Other examples include users running old versions of XWiki, looking at a documentation page that describes how a particular feature works in the current released version, and experiencing confusion.
To help address these challenges, I suggest affixing a message at the top of each documentation page, like this:
For XWiki version: 0.9.840+
As new versions of XWiki are released, the documentation team can review each documentation page and determine whether the material is out of date. If the new version differs substantially in its behavior, the message could be changed to:
For XWiki version: 0.9.840 - 0.9.970
where 0.9.970 is the last version that the page accurately documents. This will help readers to know whether the page accurately documents the version of XWiki they're using.
Eventually, the page will be revised to reflect the new functionality, but users running old versions of the XWiki software still need a way to view the documentation for their version. To deal with this, the documentation could provide a link to to the older version of the page. Something like this:
For XWiki version: 0.9.975 See also: <link>XWiki 0.9.840 - 0.9.970</link>
Thoughts?
Stephen
From: Cody Burleson <[email protected]> Reply-To: [email protected] To: [email protected] Subject: [xwiki-dev] This month is DOC month - I'll take a lead. Date: Mon, 12 Sep 2005 00:45:26 -0400
[snip]
My goal over the coming month is to play a strong role in transforming the User Guide and Administrator Guide. To achieve this goal, I pledge to work on documentation a little bit each day. Afterwards, I will probably roll into the usability and user interface focus. Until then, i hope you will accept me as a workhorse for you. Here's how you can help me (and the XWiki evolution):
-- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
------------------------------------------------------------------------
-- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
-- Ludovic Dubost XPertNet: http://www.xpertnet.fr/ Blog: http://www.ludovic.org/blog/ XWiki: http://www.xwiki.com Skype: ldubost AIM: nvludo Yahoo: ludovic -- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
I like the tag idea. But it appears that tags are not versioned (I just tested in the Sandbox). If you tag an XWiki page, and then go back and look at previous versions of that page, they are shown as tagged, even though they weren't tagged at the time they were created. For example, let's say that the current version of the document explaining XWiki permissions is tagged as applying to version-0.9.900. If you view a previous version of the permissions document that was tagged as version-0.9.840, the version-0.9.900 tag appears as well. Not good. Maybe we could use tags for this purpose _if_ when we revise the documentation for a new version of XWiki, we rename existing pages instead of revising them. Is rename functionality planned soon? Thoughts? Stephen
From: Ludovic Dubost <[email protected]> Reply-To: [email protected] To: [email protected] Subject: Re: [xwiki-dev] This month is DOC month Date: Tue, 27 Sep 2005 22:50:16 +0200
We could use the tag system for this.. Using tags
version-0.9.840
we could detect tags which start with "version-" and indeed show a "Verified on XWiki version: " text at the end of the page..
Ludovic
[snip]
Since XWiki is constantly evolving, one of the challenges of documenting it is the "moving target" phenomenon. Say you document the XWiki permissions UI. Then a new version is released, and the permissions UI changes. For a time (perhaps a very long time), the documentation is out of sync with the current released version. This will cause end-user confusion and frustration, and it's an example of how out-of-date documentation can be worse than no documentation at all. Other examples include users running old versions of XWiki, looking at a documentation page that describes how a particular feature works in the current released version, and experiencing confusion.
To help address these challenges, I suggest affixing a message at the top of each documentation page, like this:
For XWiki version: 0.9.840+
As new versions of XWiki are released, the documentation team can review each documentation page and determine whether the material is out of date. If the new version differs substantially in its behavior, the message could be changed to:
For XWiki version: 0.9.840 - 0.9.970
where 0.9.970 is the last version that the page accurately documents. This will help readers to know whether the page accurately documents the version of XWiki they're using.
Eventually, the page will be revised to reflect the new functionality, but users running old versions of the XWiki software still need a way to view the documentation for their version. To deal with this, the documentation could provide a link to to the older version of the page. Something like this:
For XWiki version: 0.9.975 See also: <link>XWiki 0.9.840 - 0.9.970</link>
Thoughts?
Stephen
Hi, This is probably solvable.. It's just that the tag system reads the objects from the most recent version and not the revised version.. Actually there is a possible way to handle the doc which is to freeze the doc at one point for version 1 and then use a new space for version 1.1 or version 2 Now that only works for major revisions.. Ludovic Stephen Schaub wrote:
I like the tag idea. But it appears that tags are not versioned (I just tested in the Sandbox). If you tag an XWiki page, and then go back and look at previous versions of that page, they are shown as tagged, even though they weren't tagged at the time they were created.
For example, let's say that the current version of the document explaining XWiki permissions is tagged as applying to version-0.9.900. If you view a previous version of the permissions document that was tagged as version-0.9.840, the version-0.9.900 tag appears as well. Not good.
Maybe we could use tags for this purpose _if_ when we revise the documentation for a new version of XWiki, we rename existing pages instead of revising them. Is rename functionality planned soon?
Thoughts?
Stephen
From: Ludovic Dubost <[email protected]> Reply-To: [email protected] To: [email protected] Subject: Re: [xwiki-dev] This month is DOC month Date: Tue, 27 Sep 2005 22:50:16 +0200
We could use the tag system for this.. Using tags
version-0.9.840
we could detect tags which start with "version-" and indeed show a "Verified on XWiki version: " text at the end of the page..
Ludovic
[snip]
Since XWiki is constantly evolving, one of the challenges of documenting it is the "moving target" phenomenon. Say you document the XWiki permissions UI. Then a new version is released, and the permissions UI changes. For a time (perhaps a very long time), the documentation is out of sync with the current released version. This will cause end-user confusion and frustration, and it's an example of how out-of-date documentation can be worse than no documentation at all. Other examples include users running old versions of XWiki, looking at a documentation page that describes how a particular feature works in the current released version, and experiencing confusion.
To help address these challenges, I suggest affixing a message at the top of each documentation page, like this:
For XWiki version: 0.9.840+
As new versions of XWiki are released, the documentation team can review each documentation page and determine whether the material is out of date. If the new version differs substantially in its behavior, the message could be changed to:
For XWiki version: 0.9.840 - 0.9.970
where 0.9.970 is the last version that the page accurately documents. This will help readers to know whether the page accurately documents the version of XWiki they're using.
Eventually, the page will be revised to reflect the new functionality, but users running old versions of the XWiki software still need a way to view the documentation for their version. To deal with this, the documentation could provide a link to to the older version of the page. Something like this:
For XWiki version: 0.9.975 See also: <link>XWiki 0.9.840 - 0.9.970</link>
Thoughts?
Stephen
------------------------------------------------------------------------
-- You receive this message as a subscriber of the [email protected] mailing list. To unsubscribe: mailto:[email protected] For general help: mailto:[email protected]?subject=help ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
-- Ludovic Dubost XPertNet: http://www.xpertnet.fr/ Blog: http://www.ludovic.org/blog/ XWiki: http://www.xwiki.com Skype: ldubost AIM: nvludo Yahoo: ludovic
participants (5)
-
Cody Burleson -
Ludovic Dubost -
Luis Arias -
Stephen Schaub -
Vern Kyle