Happy New Year, all! I was only able to take a quick look on my phone. But the docs look pretty good!
Stian, what would be the advantage of the docs being on the Apache site vs GitHub? I do like the headers and code sections better in GitHub. Personally, the Apache CMS headings seem large and h1/h2 are fairly similar. Also, I like the gray code rendering. But not a big deal. Cheers! Gale On Thu, Jan 4, 2018, 7:18 AM Stian Soiland-Reyes <st...@apache.org> wrote: > I updated > https://github.com/apache/incubator-taverna-server/blob/master/usage.md > to include some table of content - it's still very long and could > probably be split into multiple pages. > > As I fixed some things in its example XML I think it would be cumbersome > to also maintain a OpenOffice version, so I removed those. > > Would this documentation live in GitHub as it is now, or as > separate pages under > https://taverna.incubator.apache.org/documentation/server/ ? > > I had a quick go: > > http://taverna.staging.apache.org/documentation/server/3.1/ > http://taverna.staging.apache.org/documentation/server/3.1/install > http://taverna.staging.apache.org/documentation/server/3.1/usage > > Stylistically I think those look quite nice.. your views? > > (Compare with GitHub rendering > https://github.com/apache/incubator-taverna-server/blob/master/README.md > https://github.com/apache/incubator-taverna-server/blob/master/install.md > https://github.com/apache/incubator-taverna-server/blob/master/usage.md > ) > > Note as I just copied from GitHub, that there are a couple of MarkDown > differences that makes the /usage examples look broken or perhaps too red. > > > > On Wed, 6 Dec 2017 11:12:04 +0000, Stian Soiland-Reyes <st...@apache.org> > wrote: > > I had a look at the documentation included in the Taverna Server git > > repository https://github.com/apache/incubator-taverna-server > > > > Both install and usage are quite extensive, and describes both how to > > install it and how the services are invoked. > > > > For some reason these where in the repository as binary PDF and DOCX > > files which personally I find a bit odd for a server product. > > > > They also had some outdated references to Univ of Manchester and > > Taverna 2.5. > > > > > > So I changed it to more open formats MarkDown and ODT and added the > > Apache License headers: > > > > > https://github.com/apache/incubator-taverna-server/blob/master/install.md > > > https://github.com/apache/incubator-taverna-server/blob/master/install.odt > > https://github.com/apache/incubator-taverna-server/blob/master/usage.md > > https://github.com/apache/incubator-taverna-server/blob/master/usage.odt > > > > Some more tidy-up could be done (e.g. use ```code``` blocks for the XML > > examples). > > > > > > The documentation seems very overlapping (or equal) to the 2.5 > > Taverna Server documentation that also lives online in the old wiki: > > > > https://taverna.incubator.apache.org/documentation/server/ > > > > .. but I have not checked this page by page. > > > > > > > > What do you think: > > > > Is the Markdown version more or less maintainable? > > (e.g. the tables can get messy) > > > > Do we keep maintaining the OpenDocument versions (packaged as PDF in > release)? > > > > Do we keep the Markdown documentation as part of the git repository (and > > hence the Taverna Server distribution), or move it to the > > taverna.apache.org website? (it would probably work out of the > > box) > > > > > > -- > > Stian Soiland-Reyes > > http://orcid.org/0000-0001-9842-9718 > > >
