This month is DOC month - I'll take a lead.

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

This month is DOC month - I'll take a lead.

cburleso

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

[hidden email]



--
You receive this message as a subscriber of the [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
Reply | Threaded
Open this post in threaded view
|

Re: This month is DOC month - I'll take a lead.

Ludovic Dubost

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
> [hidden email]
>
> ------------------------------------------------------------------------
>
>
> --
> You receive this message as a subscriber of the [hidden email] mailing list.
> To unsubscribe: mailto:[hidden email]
> For general help: mailto:[hidden email]?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 [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
Reply | Threaded
Open this post in threaded view
|

Re: This month is DOC month - I'll take a lead.

Vern Kyle
In reply to this post by cburleso
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 <[hidden email]> 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
> [hidden email]
>  
>  
>
> --
> You receive this message as a subscriber of the [hidden email]
> mailing list.
> To unsubscribe: mailto:[hidden email]
> For general help: mailto:[hidden email]?subject=help
> ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
>
>
>


--
You receive this message as a subscriber of the [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
Reply | Threaded
Open this post in threaded view
|

Re: This month is DOC month - I'll take a lead.

kaaloo
In reply to this post by cburleso
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



--
You receive this message as a subscriber of the [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
Reply | Threaded
Open this post in threaded view
|

RE: This month is DOC month

Stephen Schaub
In reply to this post by cburleso
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 <[hidden email]>
>Reply-To: [hidden email]
>To: [hidden email]
>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 [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
Reply | Threaded
Open this post in threaded view
|

RE: This month is DOC month

cburleso

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: [hidden email]




"Stephen Schaub" <[hidden email]>

09/27/2005 03:07 PM

Please respond to
[hidden email]

To
[hidden email]
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 <[hidden email]>
>Reply-To: [hidden email]
>To: [hidden email]
>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 [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws



--
You receive this message as a subscriber of the [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
Reply | Threaded
Open this post in threaded view
|

Re: This month is DOC month

Ludovic Dubost

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: [hidden email]
>
>
>
>
> *"Stephen Schaub" <[hidden email]>*
>
> 09/27/2005 03:07 PM
> Please respond to
> [hidden email]
>
>
>
> To
> [hidden email]
> 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 <[hidden email]>
> >Reply-To: [hidden email]
> >To: [hidden email]
> >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
> [hidden email] mailing list.
> To unsubscribe: mailto:[hidden email]
> For general help: mailto:[hidden email]?subject=help
> ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
>
> ------------------------------------------------------------------------
>
>
> --
> You receive this message as a subscriber of the [hidden email] mailing list.
> To unsubscribe: mailto:[hidden email]
> For general help: mailto:[hidden email]?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 [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
Reply | Threaded
Open this post in threaded view
|

Re: This month is DOC month

cburleso

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: [hidden email]




Ludovic Dubost <[hidden email]>

09/27/2005 04:50 PM

Please respond to
[hidden email]

To
[hidden email]
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: [hidden email]
>
>
>
>
> *"Stephen Schaub" <[hidden email]>*
>
> 09/27/2005 03:07 PM
> Please respond to
> [hidden email]
>
>
>                  
> To
>                  [hidden email]
> 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 <[hidden email]>
> >Reply-To: [hidden email]
> >To: [hidden email]
> >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
> [hidden email] mailing list.
> To unsubscribe: mailto:[hidden email]
> For general help: mailto:[hidden email]?subject=help
> ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
>
> ------------------------------------------------------------------------
>
>
> --
> You receive this message as a subscriber of the [hidden email] mailing list.
> To unsubscribe: mailto:[hidden email]
> For general help: mailto:[hidden email]?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 [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws



--
You receive this message as a subscriber of the [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
Reply | Threaded
Open this post in threaded view
|

Re: This month is DOC month

Stephen Schaub
In reply to this post by Ludovic Dubost
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 <[hidden email]>
>Reply-To: [hidden email]
>To: [hidden email]
>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 [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
Reply | Threaded
Open this post in threaded view
|

Re: This month is DOC month

Ludovic Dubost

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 <[hidden email]>
>> Reply-To: [hidden email]
>> To: [hidden email]
>> 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 [hidden email] mailing list.
> To unsubscribe: mailto:[hidden email]
> For general help: mailto:[hidden email]?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 [hidden email] mailing list.
To unsubscribe: mailto:[hidden email]
For general help: mailto:[hidden email]?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws