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 [1] http://book.openscada.org/ [2] https://www.eclipse.org/eclipsescada/website.xmi On Wed, Aug 17, 2016 at 6:29 PM, Mark Stoodley <[email protected]> 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: [email protected] > ------------------------------ > We cannot solve our problems with the same thinking we used when we > created them - Albert Einstein > > > > > > > > From: Jens Reimann <[email protected]> > To: Discussions for new Eclipse projects <[email protected]> > Date: 2016/08/17 02:52 AM > Subject: Re: [incubation] project web site recommendations? > Sent by: [email protected] > ------------------------------ > > > > 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/* <https://eclipse.org/acceleo/> > > On Wed, Aug 17, 2016 at 1:17 AM, Mark Stoodley <*[email protected]* > <[email protected]>> 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* <%2B1-905-413-5831> > e-mail: *[email protected]* <[email protected]> > ------------------------------ > We cannot solve our problems with the same thinking we used when we > created them - Albert Einstein > > > > > > > _______________________________________________ > incubation mailing list > *[email protected]* <[email protected]> > To change your delivery options, retrieve your password, or unsubscribe > from this list, visit > *https://dev.eclipse.org/mailman/listinfo/incubation* > <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* <http://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 > [email protected] > To change your delivery options, retrieve your password, or unsubscribe > from this list, visit > https://dev.eclipse.org/mailman/listinfo/incubation > > > > > _______________________________________________ > incubation mailing list > [email protected] > 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 [email protected] To change your delivery options, retrieve your password, or unsubscribe from this list, visit https://dev.eclipse.org/mailman/listinfo/incubation
