Eclipse Community Forums: Eclipse Scout » [Blog Post] Documentation Platform for Eclipse Scout

Home » Eclipse Projects » Eclipse Scout » [Blog Post] Documentation Platform for Eclipse Scout

[Blog Post] Documentation Platform for Eclipse Scout [message #1694878]

Fri, 08 May 2015 12:03

Eclipse User

We have posted a new blog post "Documentation Platform for Eclipse Scout"
Please use this forum thread to share your thoughts and pose any questions.

Re: [Blog Post] Documentation Platform for Eclipse Scout [message #1695256 is a reply to message #1694878]

Wed, 13 May 2015 02:16

Eclipse User

I can see the need for a unified approach and the one you are proposing makes sense.

However, as someone having contributed both to the Wiki and the code base by contributing some code patches the one sentence that made me pause is the following:

Quote:

Use a git repository instead of a wiki to ease the maintenance on different branches.

Again, I can see why you are doing this, and it makes sense. But this will make the barrier to contribute to the documentation much higher. I have written dozens of "how to" pages on the wiki and that was trivial and cost me little time. However, as someone unfamiliar with git and sitting behind a corporate firewall, contributing three relatively small code patches took me several days and the support of someone from bsi to set up the infrastructure and to walk me through using git/gerrit correctly. If your new system is introduced the consequence for me will be that I will no longer be able to contribute to the Scout documentation as I just don't have time to put up with the whole git setup.

As an open source project, I agree documentation is vital, but if you want the community to contribute it also needs to be easy to do so. I fear that this step - while probably necessary - will make this harder than it is now.

So as a suggestion, I would encourage you to look at a way for the community to contribute documentation with a minimum of technical hassle and barriers (i.e. a way to contribute to documentation without having to go through git).

Re: [Blog Post] Documentation Platform for Eclipse Scout [message #1695262 is a reply to message #1695256]

Wed, 13 May 2015 02:36

Eclipse User

Hi Urs,

Thank you for your answer... You mention a really important point. This is the topic of my next blog post "Wiki Engine vs Git Repository".

Working without Git (or any other Source Code Control System) is not possible because of the maintenance cost to maintain several branches of the documentation.
This is something we have for the scout book but that is not possible on the Eclipse Wiki.

I hope we have considered your point, and you will be able to contribute through the GitHub web UI. Nothing to install. GitHub provides a preview of your change exactly a wiki engine does.

All you will need is:
- A GitHub account (connected to your Eclipse Profile).
- Sign the Eclipse CLA.
- Understand the principle of GitHub Pull Request (nothing to install everything is possible in the web ui of GitHub).

---

In my opinion this setup is really state of the art nowadays.

Take this documentation (random example):
How to use Azure Redis Cache with Java

At the top of the document, there is a "Edit on GitHub" link.

---

Documentation with code snippets will be a little bit complicated. But this is the price for having Code Snippet that are up-to-date (compile with the current version of Eclipse...).

I think we will be able to help you for those cases. A possibility will be embeded the code snippet in the text and migrate it to the controled code repository later on.

---

I hope this answer your concerns. Feel free to continue the discussion.

.

Re: [Blog Post] Documentation Platform for Eclipse Scout [message #1695263 is a reply to message #1695256]

Wed, 13 May 2015 02:37

Eclipse User

If you want to see the Eclipse Help we have published, you can download Scout Mars M7 and update to the latest 5.0 Version with this update site:

http://download.eclipse.org/scout/nightly/5.0

Previous Topic:	Mocking the SharedVariablesMap of the ClientSession in UnitTests
Next Topic:	Scout texts NumberTooSmall/TooLargeMessage

Goto Forum:

-=] Back to Top [=-

Current Time: Mon Oct 27 02:16:44 EDT 2025

.:: Contact :: Home ::.

Breadcrumbs

Sign up to our Newsletter