Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
Home » Eclipse Projects » 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 Go to next message
Chris Snow is currently offline 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 Go to previous messageGo to next message
Jeremie Bresson is currently online Jeremie Bresson
Messages: 758
Registered: October 2011
Senior Member
Chris Snow wrote on Fri, 30 August 2013 08:44
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.


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 #1097842 is a reply to message #1097835] Fri, 30 August 2013 08:21 Go to previous messageGo to next message
Jeremie Bresson is currently online Jeremie Bresson
Messages: 758
Registered: October 2011
Senior Member
Related topics:
* Javadoc / Eclipse help (Forum: October 2011)
* JavaDoc for Scout ? (Forum: May 2013)
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 Go to previous messageGo to next message
Andriy Fomenko is currently offline Andriy Fomenko
Messages: 21
Registered: May 2013
Junior Member
Since the last of two aforementioned "related topics" is mine, I could not resist not to comment Smile

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 Go to previous messageGo to next message
Chris Snow is currently offline 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

Re: are there any plans to move wiki content to eclipsedoc format? [message #1099747 is a reply to message #1097835] Mon, 02 September 2013 06:37 Go to previous messageGo to next message
Chris Snow is currently offline Chris Snow
Messages: 50
Registered: December 2011
Member
Hi Jeremie,

Is outputting the wiki to docbook format a possibility for your converter?

Using the docbkx plugin, docbook can be output to html, pdf and eclipse formats.

I have put a basic example here: https://github.com/snowch/scoutdoc

Many thanks,

Chris

Re: are there any plans to move wiki content to eclipsedoc format? [message #1099798 is a reply to message #1099747] Mon, 02 September 2013 08:11 Go to previous messageGo to next message
Jeremie Bresson is currently online Jeremie Bresson
Messages: 758
Registered: October 2011
Senior Member
Since I am using Eclipse Wikitext, it should be possible:
Mylyn Docs > WikiText User Guide > Markup Conversion

I do not use their ant tasks, because I had to modify some elements (MediaWiki template processing, ...), but I should be able to plug their docbook export as other output for my tool.
Re: are there any plans to move wiki content to eclipsedoc format? [message #1099816 is a reply to message #1099798] Mon, 02 September 2013 08:47 Go to previous messageGo to next message
Chris Snow is currently offline Chris Snow
Messages: 50
Registered: December 2011
Member
Thanks Jeremie.

One thing I'm still mulling over are the following options, either:

1) Automate documentation production from wiki contents
2) Manually extract contents from wiki and incorporate into other documentation (e.g. into https://github.com/snowch/scoutdoc)

Due to the nature of wiki's no one seems to have overall editing control, therefore any documentation extracted automatically can not be guaranteed to be high quality. Is a manual process needed where content is manually extracted, verified, edited, etc to ensure high quality documentation?

Re: are there any plans to move wiki content to eclipsedoc format? [message #1100507 is a reply to message #1099816] Tue, 03 September 2013 07:38 Go to previous messageGo to next message
Matthias Zimmermann is currently offline Matthias Zimmermann
Messages: 81
Registered: February 2010
Member
Javadoc
We should definitively look at generating javadoc documentation from the sources and publish them (as seen for the xtext project [1]).

Scout Book
The next offline capable documentation is the Scout book [2].
It provides a good start but it's content is still pretty basic.
However, the situation will improve as we are shipping future releases.

Wiki/Eclipse Help
Creating offline readable content from the Eclipse Scout Wiki pages is something we have discussed previously.
The rationale behind this approach can be summarized as follows
* Wiki pages provide a low entry barrier, which reduces the pain to fix/contribute content
* The Wiki pages should be the primary source for Scout tutorials
* We cannot afford too many parallel sources of documentation
* Adding Eclipse Help as an individual channel is too expensive to build and maintain
* However, transforming wiki tutorials to the Eclipse Help format could be feasible

Some components for such a converter have already been prototyped, other aspects are yet to be defined/built
1) Automation of transforming wiki content seems feasible (see prototype)
2) Amending the building to include the Eclipse Help is feasible too
3) We also need a sound concept for wiki monitoring for the tutorials to be converted
4) Testing of the Eclipse help tutorials would have to be done using published milestones

Reporting Bugs
While we try to update the Scout documentation while we add new features there are still many areas that lack a meaningful documentation. Sometimes, documentation is missing for historical reasons, sometimes developers are just too busy developing.

To move forward, we would like to suggest that you create individual bugzilla tickets for individual pieces of missing documentation that you really care. In that case we can focus the documentation on the parts the community really cares - and - we can assign a fixed documentation bug back to the reporting person for verification.

Please note that you may use bugzilla for missing/bad javadoc and wiki documentation. For issues with the Scout book please use the Github issue tracker [3].

[1] http://download.eclipse.org/modeling/tmf/xtext/javadoc/2.4/
[2] http://wiki.eclipse.org/Scout/Book/3.9
[3] https://github.com/BSI-Business-Systems-Integration-AG/scoutbook/issues
Re: are there any plans to move wiki content to eclipsedoc format? [message #1100543 is a reply to message #1100507] Tue, 03 September 2013 08:30 Go to previous message
Chris Snow is currently offline Chris Snow
Messages: 50
Registered: December 2011
Member
Quote:
* Adding Eclipse Help as an individual channel is too expensive to build and maintain


The maven docbkx tools allow you to have one source which is in docbook format and from that generate pdf, html, eclipse help and other formats.

Docbkx page: https://code.google.com/p/docbkx-tools
See an example here: https://github.com/snowch/scoutdoc

docbkx is used on many open source projects.

Caveat: I have extensively used pdf and html with docbkx, but have not done much with eclipse help in the past.
Previous Topic:Scout calendar service information
Next Topic:Scout with SQLite
Goto Forum:
  


Current Time: Wed Oct 22 09:54:15 GMT 2014

Powered by FUDForum. Page generated in 0.02109 seconds
.:: Contact :: Home ::.

Powered by: FUDforum 3.0.2.
Copyright ©2001-2010 FUDforum Bulletin Board Software