Skip to main content


Eclipse Community Forums
Forum Search:

Search      Help    Register    Login    Home
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 16:03 Go to next message
Matthias Zimmermann is currently offline Matthias ZimmermannFriend
Messages: 208
Registered: June 2015
Senior Member
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 06:16 Go to previous messageGo to next message
Urs Beeli is currently offline Urs BeeliFriend
Messages: 573
Registered: October 2012
Location: Bern, Switzerland
Senior Member
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 06:36 Go to previous messageGo to next message
Jeremie Bresson is currently offline Jeremie BressonFriend
Messages: 1252
Registered: October 2011
Senior Member
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 06:37 Go to previous message
Jeremie Bresson is currently offline Jeremie BressonFriend
Messages: 1252
Registered: October 2011
Senior Member
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:
  


Current Time: Tue Mar 19 07:17:43 GMT 2024

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

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

Back to the top