You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@taverna.apache.org by Stian Soiland-Reyes <st...@apache.org> on 2017/12/06 11:12:04 UTC
Taverna Server documentation
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
Re: Taverna Server documentation
Posted by Stian Soiland-Reyes <st...@apache.org>.
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 <ia...@gmail.com> 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: dev@taverna.incubator.apache.org
> 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 <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
>
--
Stian Soiland-Reyes
http://orcid.org/0000-0001-9842-9718
Re: Taverna Server documentation
Posted by Gale Naylor <Ga...@noventussolutions.com>.
Awesome! Thanks :)
On Fri, Jan 19, 2018, 6:48 AM Stian Soiland-Reyes <st...@apache.org> wrote:
> On 19 January 2018 at 03:14, Gale Naylor <ga...@noventussolutions.com>
> wrote:
> > Happy New Year @Ian and @Stian and all! Things are going well. Keep
> > thinking I'll have time to do more than lurk, but not so far. :)
> > Looks like things are going well for you, too!
>
> Cheers! I guess we're trundling along! :)
>
> No worries if you don't have time, it's limited for all of us..
>
> Any effort welcome folks, small or large; opinions, code, docs and
> bitcoins welcome :) And don't feel bad if you are busy, let's keep it
> fun.
>
> --
> Stian Soiland-Reyes
> http://orcid.org/0000-0001-9842-9718
>
Re: Taverna Server documentation
Posted by Stian Soiland-Reyes <st...@apache.org>.
On 19 January 2018 at 03:14, Gale Naylor <ga...@noventussolutions.com> wrote:
> Happy New Year @Ian and @Stian and all! Things are going well. Keep
> thinking I'll have time to do more than lurk, but not so far. :)
> Looks like things are going well for you, too!
Cheers! I guess we're trundling along! :)
No worries if you don't have time, it's limited for all of us..
Any effort welcome folks, small or large; opinions, code, docs and
bitcoins welcome :) And don't feel bad if you are busy, let's keep it
fun.
--
Stian Soiland-Reyes
http://orcid.org/0000-0001-9842-9718
RE: Taverna Server documentation
Posted by Gale Naylor <ga...@noventussolutions.com>.
Happy New Year @Ian and @Stian and all! Things are going well. Keep
thinking I'll have time to do more than lurk, but not so far. :)
Looks like things are going well for you, too!
Cheers!
Gale
On Jan 18, 2018 6:22 AM, "Ian Dunlop" <ia...@gmail.com> 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: dev@taverna.incubator.apache.org
> 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 <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 <
> stain@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
>
>
RE: Taverna Server documentation
Posted by Ian Dunlop <ia...@gmail.com>.
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: dev@taverna.incubator.apache.org
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 <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
Re: Taverna Server documentation
Posted by Stian Soiland-Reyes <st...@apache.org>.
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
Re: Taverna Server documentation
Posted by Gale Naylor <Ga...@noventussolutions.com>.
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
> >
>
Re: Taverna Server documentation
Posted by Stian Soiland-Reyes <st...@apache.org>.
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
>