Hmm.. I had a good fight with Markdown. It seemed to think that the indentation of the config block (intending <pre>) was actually a continuation of the unordered list above.. How lovely to not have start-stop tags, uh..
See now at http://taverna.staging.apache.org/documentation/server/3.1/install#configuration-property-list (quite a few ctrl-shift-R seems to be needed) The Workflow State diagram I hacked together quickly using https://www.draw.io/ as the one in the .docx was hard to get to look good outside Word. So this looks kind of OK, so I'll link to that in the announcement. On 18 January 2018 at 14:22, Ian Dunlop <[email protected]> wrote: > Hello, > > Styling seems to have gone a bit crazy on the install guide “Configuration > Property List” part, lot’s of bold headers. > (http://taverna.staging.apache.org/documentation/server/3.1/install) > In http://taverna.staging.apache.org/documentation/server/3.1/usage some of > the code blocks haven’t rendered correctly, you can still see the ```xml > markup in some places. > Also why is the workflow state not rendered as a Taverna workflow (BTW that’s > a joke 😉) > > Overall, good job. > @Gale Happy New Year. Great to hear from you. Hope things are going well for > you. > > Cheers, > > Ian > > Sent from Mail for Windows 10 > > From: Stian Soiland-Reyes > Sent: 18 January 2018 12:41 > To: [email protected] > Subject: Re: Taverna Server documentation > > 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> >>> 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 > -- Stian Soiland-Reyes http://orcid.org/0000-0001-9842-9718
