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
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
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.
Hi, Jim Stuttard a écrit :
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.
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.
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
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
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@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
On Sat, 18 Jun 2005 13:59:38 +0200, Ludovic Dubost <ludovic@xwiki.com> wrote:
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. Do you have a preference between publishing intellij and or eclipse models or exporting them to xwiki as graphviz or jpeg or what?
I'm currently pushing the javadoc and junit results on the automated build platform:
+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.. 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.
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 ?
As before just your top level engine diagram.
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.
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
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
participants (3)
-
Jim Stuttard -
Ludovic Dubost -
Stephen Schaub