Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [incubation] project web site recommendations?
Hello Mark,

for documentation we went a rather boring way with Docbook generating HTML [1]. That could have been put on the same site, but since OpenSCADA is an extension to Eclipse NeoSCADA, we did it there. That is also why it ended up it a different git repository. The pro side of docbook is that you can easily re-brand or extend the existing documentation if you need.

For the Eclipse hosted website we stuck with a plain project web site that you can see. Listing different releases: yes, but there is only one instance of the data backing this instance [2], so no multi-branch, multi-release way there.

The wiki worked fine in general. But as you said it is, well, a challenge to keep it up to date, and for the wiki we only documented the most recent release.

Jens

On Wed, Aug 17, 2016 at 6:29 PM, Mark Stoodley <mstoodle@xxxxxxxxxx> wrote:
Thanks for the response, Jens.

On a quick scan of your site, it looks to me like you maintain most of your documentation in your wiki, so it lives separately from your code and is accessible from your web site only by the wiki link.

Have you had any challenges around keeping the wiki documentation up to date when people change the code? Do you support multiple releases at the same time, and if so, how have you handled documentation that has changed across those releases?
Mark Stoodley 8200 Warden Avenue
Senior Software Developer Markham, L6G 1C7
IBM Runtime Technologies Canada
Phone:+1-905-413-5831 
e-mail:mstoodle@xxxxxxxxxx 
We cannot solve our problems with the same thinking we used when we created them - Albert Einstein
 
 






From:        Jens Reimann <jreimann@xxxxxxxxxx>
To:        Discussions for new Eclipse projects <incubation@xxxxxxxxxxx>
Date:        2016/08/17 02:52 AM
Subject:        Re: [incubation] project web site recommendations?
Sent by:        incubation-bounces@eclipse.org



So what worked quite well for the Eclipse NeoSCADA project is to use a static web page generated using the "Acceleo" Model to Text tools [1]. Checking in the static web pages in the web git repository and the sources to the generator to the "releng" code git repository. That way website and code was split up.

Of course you are down to coding manual HTML to some degree, although Acceleo helps a lot. If you use some sort of HTML toolkit (like bootstrap) you don't need to worry too much.

Then again if you don't update your templates for a few years it starts to look old ;-)

[1] https://eclipse.org/acceleo/

On Wed, Aug 17, 2016 at 1:17 AM, Mark Stoodley <mstoodle@xxxxxxxxxx> wrote:
The OMR project is trying to work out what to do with our web site and looking at a few options:
        1. web site sources in a directory in our GitHub repo (keep docs and site beside code for easier maintenance)
        2. web site sources in a separate branch in our GitHub repo
        3. web site sources maintained at our Eclipse project web site git repo

In the first two cases, we would use a Hudson job to mirror the web site source to our Eclipse web site repository and to generate the actual web site, as I know some Eclipse projects already do.

Just wondering if there are other options we should consider or recommendations from other projects on what's worked best for you in managing your web site / source code.

In discussion on our mailing list, there is some attraction to maintaining docs alongside the source code in the same pull requests as well as to be able to branch the documentation along with the code for releases. There are also concerns about binary artifacts and repository clone times if the web site is in the same repository as the source code. I'd be particularly interested if you have any advice on how impactful these issues have been for your project.

Thanks!
Mark Stoodley 8200 Warden Avenue
Senior Software Developer Markham, L6G 1C7
IBM Runtime Technologies Canada
Phone:+1-905-413-5831 
e-mail:mstoodle@xxxxxxxxxx 
We cannot solve our problems with the same thinking we used when we created them - Albert Einstein
 
 





_______________________________________________
incubation mailing list
incubation@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/incubation




--
Jens Reimann
Senior Software Engineer / EMEA ENG Middleware
Werner-von-Siemens-Ring 14
85630 Grasbrunn
Germany
phone: +49 89 2050 71286
_____________________________________________________________________________

Red Hat GmbH, www.de.redhat.com,

Registered seat: Grasbrunn, Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Paul Argiry, Charles Cachera, Michael Cunningham, Michael O'Neill_______________________________________________
incubation mailing list
incubation@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/incubation




_______________________________________________
incubation mailing list
incubation@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://dev.eclipse.org/mailman/listinfo/incubation




--
Jens Reimann
Senior Software Engineer / EMEA ENG Middleware
Werner-von-Siemens-Ring 14
85630 Grasbrunn
Germany
phone: +49 89 2050 71286
_____________________________________________________________________________

Red Hat GmbH, www.de.redhat.com,
Registered seat: Grasbrunn, Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Paul Argiry, Charles Cachera, Michael Cunningham, Michael O'Neill

Back to the top