I think we can say the distinction is if the documentation is code-related (stays in git aka GitHub) or user-related (stays on our website). With Taverna Server it's a bit tighter together.. all the API examples could change from one release to another and easily be outdated.
Agree on that the headers and code sections looks better in GtHub rendering. It could be that we can make some tweaks to our website CSS to make it more similar? I think we are using Bootstrap and a couple of custom overrides in https://github.com/apache/incubator-taverna-site/tree/trunk/content/css On 5 January 2018 at 15:50, Gale Naylor <ga...@noventussolutions.com> wrote: > 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 >> > >> -- Stian Soiland-Reyes http://orcid.org/0000-0001-9842-9718
