Home » Eclipse Projects » Eclipse Scout » are there any plans to move wiki content to eclipsedoc format?
are there any plans to move wiki content to eclipsedoc format? [message #1097782] |
Fri, 30 August 2013 06:44 |
Chris Snow Messages: 50 Registered: December 2011 |
Member |
|
|
As a newbie to scout, I keep hitting the same two issues:
1) reference documentation is only available online (on the wiki)
2) reference documentation is not available for new (and some old) features
By reference documentation, I mean content like howtos.
Why is the wiki used for reference document and not eclipsedoc?
Eclipsedoc would give the following benefits:
a) eclipsedoc can be viewed offline
b) eclipsedoc documentation is **much** easier to navigate than the wiki - eclipsedoc is much more accessible from the eclipse IDE
c) eclipsedoc would encourage new features to be documented with each scout release
Points a and b are important because there seems to be quiet a few implementation patterns (e.g. CRUD) that I have to keep going back to the wiki for until the process becomes ingrained in my memory.
Point c is quite an important issue for me. New features are advertised with each scout release, but without adequate documentation those new features are only accessible to experienced users. New features are meaningless to me if I can't implement them because they aren't documented. For example, I have hit a roadblock, I would like to try using Calendar Services, Bookmark Services, and Extension bundles but the documentation is not complete so I can't progress.
In summary, my experience as a new user: Eclipse scout is a good product, but the documentation needs more consideration to make scout a really great product.
[Updated on: Fri, 30 August 2013 07:11] Report message to a moderator
|
|
|
Re: are there any plans to move wiki content to eclipsedoc format? [message #1097835 is a reply to message #1097782] |
Fri, 30 August 2013 08:12 |
Jeremie Bresson Messages: 1252 Registered: October 2011 |
Senior Member |
|
|
Chris Snow wrote on Fri, 30 August 2013 08:44In summary, my experience as a new user: Eclipse scout is a good product, but the documentation needs more consideration to make scout a really great product.
I absolutely agree with you
Some background about Eclipse Scout:
Scout as closed-source company framework is a mature product. Eclipse Scout (that replaced the closed source Scout) is a relatively new project.
We have invested a lot to clear the Technical debt: we have cleaned the code base to be eclipse compliant (EPL, IP Clean), we have moved to a modern source repository (Git) allowing easy contribution and reviews, we have rewritten the build to use CBI, we have started to move our internal test suite to our open-source repository.
In the same time we have continued the product development (web ui using RAP, mobile support, extensions, binary core support ...). It is a great reward to have people like you telling us that Eclipse Scout is a great product.
But (there is a "But"), documentation is a domain were we can do much better. I think we have been transparent in our process since the beginning
Documentation - current state:
* Wiki: collaborative process. Everyone can contribute (by editing the wiki), there is a very low Barriers to entry. No space limitation, every topic can be addressed in the wiki. See also: eclipse scout wiki contributions.
* Book: we have started a book. It is open-source, we also expect everyone to contribute and have started to get feedback. Because the format is defined (it is book, space is limited) we want to provide a good overview of scout in a reasonable amount of pages. The contributions are reviewed, the Table of content is defined. See also: book contribution.
* Forum: We try to answer every questions asked in our forum. This is an answer to the lack of documentation. Because the life time of a topic is short (sometimes some user use the search engine, but it is not always the case), we try to move the content from the forum to an appropriate wiki page.
To be discussed:
You are right we need process to update documentation. Opening bugs as you suggested here is a way to go. I did not answer yet, because I am still wondering if we want this bug tracking overhead or if the forum is enough.
The lack of eclipse-help has been mentioned before. This is why I prototyped a convertor: eclipse wiki to eclipse help (reusing the mylyn docs wikitext project). See also: tool overview.
Maybe I should work back on the project, to finish it (meaning contributing a first version of the eclipse help, based on the wiki content).
It is possible that this is good enough for the start and will encourage more people to contribute to the wiki.
You are proposing a new channel: writing eclipse help from scratch (source check in in our git repository).
I agree this is a way to get a proper eclipse help. But such a process will be very time consuming. At the end there is no guarantee at all that it will "encourage new features to be documented with each scout release" (your point c). At the end it is always a matter of time, we have limited resources, and we need to do the best out of it.
Here is my vision of the topic. I would be interested in your feedback (from you and from other interested parties).
|
|
| |
Re: are there any plans to move wiki content to eclipsedoc format? [message #1097983 is a reply to message #1097842] |
Fri, 30 August 2013 12:33 |
Andriy Fomenko Messages: 24 Registered: May 2013 |
Junior Member |
|
|
Since the last of two aforementioned "related topics" is mine, I could not resist not to comment
I think Scout documentation will never be perfect just from the nature of the free/open project: it is simply not enough resources dedicated to this.. and community wise, it is no much drive/appeal to go past forum into a full-pledged documentation... It will increase effort/cost exponentially, so it is unlikely to happen, IMHO.
I still think that some "minimum" / "critical mass" needs to be added in a form not burdening maintainers/contributors.
I think JavaDoc is the very minimum to get a class/packages reference (directly from the source code compilation), as otherwise what I do myself is digging through the code every time I need to see how particular method works or what call dependencies might be involved... which is not really productive... this is what JavaDoc is for.
I've checked a "crowd-sourced book" draft: got some info from it, but I think a contribution process is confusing/complicated for hectic community to follow...
WiKi seem to be a way to go for easier knowledge sharing with low entry barrier. In my view, some structure improvement may be needed to introduce base concepts in the easier to digest way, but overall it was the most useful resource on the Scout for me. To my shame, I still do not feel knowledgeable enough to contribute content there.. (likely like some other people too).
Jeremie: I believe your CONVERTOR would be GREAT once incorporated into release cycle, as I find myself working over cell-network internet periodically and having an offline documentation set would be great! Even with always-connected mode, having multiple browser tabs opened "for just in case" is a resource hog.
[Updated on: Fri, 30 August 2013 12:35] Report message to a moderator
|
|
|
Re: are there any plans to move wiki content to eclipsedoc format? [message #1098029 is a reply to message #1097983] |
Fri, 30 August 2013 13:55 |
Chris Snow Messages: 50 Registered: December 2011 |
Member |
|
|
One of the other problems with Wiki's is that you are allowing developers of a feature to skip creating the documentation for the feature that they have created.
This usually means that someone else has to learn the feature before they document the feature on the wiki:
- through communication with the developer
- through reverse engineering if the developer is not available
The amount of time I have spent reverse engineering code to understand it confirms my belief that the process of second hand documentation destroys the principles of encapsulation as you have to get under the hood to understand what is going on.
IMHO, the only way a wiki can work effectively is when the developer of a feature also writes the wiki documentation for the feature so that the documentation is available as soon as the feature becomes available.
[Updated on: Fri, 30 August 2013 13:57] Report message to a moderator
|
|
| | | | | |
Goto Forum:
Current Time: Thu Mar 28 10:26:20 GMT 2024
Powered by FUDForum. Page generated in 0.02204 seconds
|