search

common-workflow-language / user_guide

The CWL v1.0 - v1.2 user guide
http://www.commonwl.org/user_guide/
Other
42 stars 67 forks source link

Proposal: Improve user-guide links to specification #346

Closed fmigneault closed 1 year ago

fmigneault commented 1 year ago

I have often noticed when doing a simple Google search about CWL terms that the User-Guide comes up first most of the time. When going through it, we obtain general usage examples which often covers most basic use-cases, but when more information is needed about a certain item or that more advanced usage is sought, there is no obvious reference to the corresponding specification.

For example, if I was interested about outputs definition and landed on this page: https://www.commonwl.org/user_guide/topics/outputs.html And then started reading about outputBinding and glob, there is no reference to https://www.commonwl.org/v1.2/CommandLineTool.html#CommandOutputBinding

The User-Guide topic presents in that case general usage of glob, but without looking (and knowing where to look in the specification), I would miss out on other important details like that it can be a list of expressions or any of its other intricacies.

Whenever a term (often wrapped in code format) is mentioned, there should be a link reference to the specification where its explicit definition is provided. In some cases it is already done, like in https://www.commonwl.org/user_guide/topics/parameter-references.html, but there are still a lot of other pages missing links.

swzCuroverse commented 1 year ago

Thanks for pointing this out. Often we think that people are reading the User Guide front to back, but really people might pop in on any page via Google so it is good that we provide context and links for them.