17 Jun
2005
17 Jun
'05
11:39 p.m.
Are there any plans to develop improved documentation for the 1.0 release?
In the initial wiki installation, it would be nice if there were a nice "Getting
Started" guide for users that explains how to do basic wiki administration, etc.
One way to develop this might be to create a virtual wiki at something like home.xwiki.org
where current Xwiki users could contribute to developing the initial home page that
appears in a default installation. Thoughts?
Stephen
18 Jun
18 Jun
1:10 a.m.
New subject: [xwiki-dev] Documentation efforts for 1.0 release
Hi Stephen,
Sure we want much better documentation than there is now. These are all
good ideas..
One of the things we need to solve first is how the documentation will
be managed.
Currently there is:
- a FAQ on XWiki.com which has mainly general stuff and some stuff
related only to XWiki.com
- a Tutorial to XWiki on XWiki.com
- a default wiki for XWiki.com (in French and English)
- a default wiki for offline installs (in English only)
The offline install default wiki differs very slightly from the
XWiki.com default wiki. One could be derived from the other.
I'm not sure the XWiki documentation should be copied over to the
offline wiki install. I'm more a fan of a link to the online
documentation. Maybe we could trick the wiki to display this
documentation inside the local wiki look and feel (if the skin was
changed) using InterWiki includes (which would be needed to be developed
but would make a lot of sense).
Now I think we should move the documentation to the xwiki.org web site
in a specific area. Using some XWiki classes, we can mark the
documentation articles that are specific to XWiki.com.
We can definitively open the default wiki to developer's editing so that
people can contribute to it's improvement. We can then have an automated
export to XML so that we can release it on ObjectWeb regularly.
Documentation is a weak part of XWiki. We are definitively looking for
people that can help in this area.
Ludovic
Stephen Schaub a écrit :
Are there any plans to develop improved documentation
for the 1.0 release?
In the initial wiki installation, it would be nice if there were a
nice "Getting Started" guide for users that explains how to do basic
wiki administration, etc.
One way to develop this might be to create a virtual wiki at something
like home.xwiki.org where current Xwiki users could contribute to
developing the initial home page that appears in a default
installation. Thoughts?
Stephen
--
Ludovic Dubost
XPertNet: http://www.xpertnet.fr/
Blog: http://www.ludovic.org/blog/
XWiki: http://www.xwiki.com
Skype: ldubost AIM: nvludo Yahoo: ludovic
1:29 p.m.
New subject: [xwiki-dev] Documentation efforts for 1.0 release Round-trip documentation
Hi,
Thanks Ludovic for the roadmap and the diagrams.
AFAIR you mentioned that you were using IntelliJ. Is that your XWiki.com
default tool? How many of us like me will be using Eclipse and or Rose and
or AspectJ? Or some other suggestion.
If we were round-trip engineering then there would be a question to
discuss about diagram import/export between tools. I am a committed
automatic documentalist. Round-trip seems to me the sensible way to meet
the demand for learning materials
with guaranteed accuracy and currency.
You're current class diagrams are jpegs. We have Graphviz as a built in
tool.
WDYT?
I'm not sure the XWiki documentation should be
copied over to the
offline wiki install. I'm more a fan of a link to the online
documentation.
Sorry to disagree but I want full documentation for my own experiments on
my own offline wiki so I need a downloadable documentation framework.
Now I think we should move the documentation to the
xwiki.org web site
in a specific area. Using some XWiki classes, we can mark the
documentation articles that are specific to XWiki.com.
We can definitively open the default wiki to developer's editing so that
people can contribute to it's improvement. We can then have an automated
export to XML so that we can release it on ObjectWeb regularly.
Documentation is a weak part of XWiki. We are definitively looking for
people that can help in this area.
I have started listing some of the use cases. They appear to start
something like:
__UC__1. Render XWiki Documents
__UC__1. Verify Authorisation and Rights
__UC__1. Read Documents
__UC__1. Access and Modify Documents, Objects
__UC__1. Search Documents and Objects
__UC__1. Read User and Rights
__UC__1. Read/Write Object/Classes
There are plenty turning up nearly every day on Jira but they are
technical.
IMHO The current (largely implicit) business use case hierarchy doesn't
quite seem abstract enough or explicitly and correctly nested. It just
seems that way, I have no examples cos I'm talking about a missing level
or lack of separation of levels.
IMHO The classes seem too large to me and seems to mix model content and
model management functions in the same class.
Is that unfair?
Regards
Jim
PS As an ex editor I volunteer to correct the english on the XWiki sites
if that's any use? If you want to mail me any drafts offline I will
happily try and correct those.
1:59 p.m.
New subject: [xwiki-dev] Documentation efforts for 1.0 release Round-trip documentation
Hi,
Jim Stuttard a écrit :
In this case we probably need some "automated" copy when we release a
offline wiki database. Thanks to Jeremi's work, we might be able to
package the documentation as an XWiki Application which would mean we
could also upgrade them.
Is that for user doc or developer doc ? It could actually apply to both..
For users then the next step is: comments, attachements, versioning,
interact with specific applications
For developers then the next step is: Create forms, create templates,
access priviledged API, create macros & functions, write plugins
Hi,
Thanks Ludovic for the roadmap and the diagrams.
AFAIR you mentioned that you were using IntelliJ. Is that your
XWiki.com default tool? How many of us like me will be using Eclipse
and or Rose and or AspectJ? Or some other suggestion.
Currently we are maintaining compatibility with IntelliJ and Eclipse +
building with ant for the automated build. We are looking at maven or
maven2 for future automated build.
We have an open source licence for XWiki developpement for IntelliJ. I
still prefer IntelliJ because of productivity reasons (I even payed my
licence before they created the open source program).
If we were round-trip engineering then there would be
a question to
discuss about diagram import/export between tools. I am a committed
automatic documentalist. Round-trip seems to me the sensible way to
meet the demand for learning materials
with guaranteed accuracy and currency.
You're current class diagrams are jpegs. We have Graphviz as a built
in tool.
WDYT?
I've very open to that.. I don't have much experience on this so I would
need help setting up things like that.
I'm currently pushing the javadoc and junit results on the automated
build platform:
See http://build.xpertnet.biz/doc/
I'm not
sure the XWiki documentation should be copied over to the
offline wiki install. I'm more a fan of a link to the online
documentation.
Sorry to disagree but I want full documentation for my own experiments
on my own offline wiki so I need a downloadable documentation framework.
Now I think we
should move the documentation to the xwiki.org web site
in a specific area. Using some XWiki classes, we can mark the
documentation articles that are specific to XWiki.com.
We can definitively open the default wiki to developer's editing so that
people can contribute to it's improvement. We can then have an automated
export to XML so that we can release it on ObjectWeb regularly.
Documentation is a weak part of XWiki. We are definitively looking for
people that can help in this area.
I have started listing some of the use cases. They appear to start
something like:
__UC__1. Render XWiki Documents
__UC__1. Verify Authorisation and Rights
__UC__1. Read Documents
__UC__1. Access and Modify Documents, Objects
__UC__1. Search Documents and Objects
__UC__1. Read User and Rights
__UC__1. Read/Write Object/Classes
There are plenty turning up nearly every day on Jira but they are
technical.
IMHO The current (largely implicit) business use case hierarchy
doesn't quite seem abstract enough or explicitly and correctly
nested. It just seems that way, I have no examples cos I'm talking
about a missing level or lack of separation of levels.
Are you talking about the FAQ, Jira, the web site ? For the FAQ we start
to have a good number of documents. Indeed we can start reorganizing,
nesting, etc.. It's part of the plan to redo the web site (both
XWiki.com which should show the business value of XWiki and xwiki.org
which should help user's and developer's find everything they need and
allow them to interact.
IMHO The classes seem too large to me and seems to mix
model content
and model management functions in the same class.
Is that unfair?
It's probably not that good to mix that.. That will probably need some
refactoring for XWiki 2.0. It's going to be tough to fix that for the
first release.
Regards
Jim
PS As an ex editor I volunteer to correct the english on the XWiki
sites if that's any use? If you want to mail me any drafts offline I
will happily try and correct those.
------------------------------------------------------------------------
--
You receive this message as a subscriber of the xwiki-dev(a)objectweb.org mailing list.
To unsubscribe: mailto:xwiki-dev-unsubscribe@objectweb.org
For general help: mailto:sympa@objectweb.org?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
19 Jun
19 Jun
2:48 p.m.
New subject: Documentation efforts for 1.0 release Round-trip documentation + use case templates link
On Sat, 18 Jun 2005 13:59:38 +0200, Ludovic Dubost <ludovic(a)xwiki.com>
wrote:
Do you have a preference between publishing
intellij and or eclipse models
or exporting them to xwiki as graphviz or jpeg or what?
Indeed but it just you package relations from your engine diagram. How it
fits with road map, faq, jira etc I'll spend some time working out.
As before just your top level engine diagram.
For anyone who might want to work on the text use cases, Scott Ambler has
standard templates free for use and download for use cases, test case,
business rules, change request etc on his site at:
http://www.ronin-intl.com/downloads/
Cheers
Jim
Currently we are maintaining compatibility with
IntelliJ and Eclipse +
building with ant for the automated build. We are looking at maven or
maven2 for future automated build.
We have an open source licence for XWiki developpement for IntelliJ. I
still prefer IntelliJ because of productivity reasons (I even payed my
licence before they created the open source program).
How do we download an open source version of IntelliJ?
> If we were round-trip engineering then there would
be a question to
> discuss about diagram import/export between tools.
Stupid me. We have the source code and that can squirt the format of any
modelling tool. We don't need to import or export diagrams from different
modelling tools which should (joke) all produce the same result from the
same source. We just have to decide how to share and use them. Do you have
a preference between publishing intellij and or eclipse models or
exporting them to xwiki as graphviz or jpeg or what?
__DevUC__1 Publish UML models
If we want to import other people's models then we would have to put both
intellij and eclipse models in subversion. The common source would keep
them in synch. If round-trip is adopted then all developers
You're
current class diagrams are jpegs. We have Graphviz as a built
in tool.
WDYT?
I've very open to that.. I don't have much experience on this so I would
need help setting up things like that. I'm currently pushing the javadoc and junit
results on the automated
build platform:
See http://build.xpertnet.biz/doc/
+1
In this case we probably need some
"automated" copy when we release a
offline wiki database. Thanks to Jeremi's work, we might be able to
package the documentation as an XWiki Application which would mean we
could also upgrade them.
>> Now I think we should move the documentation to the xwiki.org web site
>> in a specific area. Using some XWiki classes, we can mark the
>> documentation articles that are specific to XWiki.com.
+1
>> We can definitively open the default wiki to
developer's editing so
>> that
>> people can contribute to it's improvement. We can then have an
>> automated
>> export to XML so that we can release it on ObjectWeb regularly.
+1
>> Documentation is a weak part of XWiki. We are
definitively looking for
>> people that can help in this area.
I'll continue with use cases then.
I have started listing some of the use cases. They appear to start
something like:
__UC__1. Render XWiki Documents
__UC__1. Verify Authorisation and Rights
__UC__1. Read Documents
__UC__1. Access and Modify Documents, Objects
__UC__1. Search Documents and Objects
__UC__1. Read User and Rights
__UC__1. Read/Write Object/Classes
Is that for user doc or developer doc ? It could actually apply to both..
For users then the next step is: comments,
attachements, versioning,
interact with specific applications
For developers then the next step is: Create forms,
create templates,
access priviledged API, create macros & functions, write plugins
Will integrate
these into user, dev and common threads.
There are plenty turning up nearly every day on Jira but they are
technical.
IMHO The current (largely implicit) business use case hierarchy
doesn't quite seem abstract enough or explicitly and correctly
nested. It just seems that way, I have no examples cos I'm talking
about a missing level or lack of separation of levels.
Are you talking about the FAQ, Jira, the web site ? For the FAQ we start
to have a good number of documents.
Agreed
Indeed we can start reorganizing,
nesting, etc..
+1
It's part of the plan to redo the web site (both
XWiki.com which should show the business value of XWiki and xwiki.org
which should help user's and developer's find everything they need and
allow them to interact.
Great.
IMHO The
classes seem too large to me and seems to mix model content
and model management functions in the same class.
Is that unfair?
It's probably not that good to mix that.. That will probably need some
refactoring for XWiki 2.0. It's going to be tough to fix that for the
first release.
18 Jun
18 Jun
9:16 p.m.
New subject: [xwiki-dev] Documentation efforts for 1.0 release
I'm not sure the XWiki documentation should be
copied over to the offline
wiki install.
I do think that offline documentation is important for a couple of reasons:
* Some people run wikis behind firewalls where access to xwiki.org may be
intermittent or unavailable
* The documentation online may be for a more recent version than the local
wiki is running
We can definitively open the default wiki to
developer's editing so that
people can contribute to it's improvement. We can then have an automated
export to XML so that we can release it on ObjectWeb regularly.
Great -- I look forward to contributing when you can set this up.
XWiki is a great product -- and it's time for the documentation to reflect
the greatness of the product!
Stephen
7029
days inactive
7031
days old
5 comments
3 participants
participants (3)
-
Jim Stuttard -
Ludovic Dubost -
Stephen Schaub