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