From f386fb26da6ab30dca5ae9221008173e5dd9768d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9Cgathoni-k=E2=80=9D?= <“maryg.kahiga@gmail.com”>
Date: Thu, 13 Oct 2022 16:24:27 +0300
Subject: [PATCH] Add descriptive link texts

---
 src/introduction/quick-start.md                | 14 +++++++-------
 src/topics/custom-types.md                     |  2 +-
 src/topics/file-formats.md                     |  4 ++--
 src/topics/specifying-software-requirements.md |  3 +--
 4 files changed, 11 insertions(+), 12 deletions(-)

diff --git a/src/introduction/quick-start.md b/src/introduction/quick-start.md
index 0e153bee..28783d7c 100644
--- a/src/introduction/quick-start.md
+++ b/src/introduction/quick-start.md
@@ -93,13 +93,13 @@ files.
 
 ## Learn more
 
-- Continue reading the next sections of this User Guide!
-- List of CWL Implementations: <https://www.commonwl.org/implementations/>
-- The `common-workflow-language` organization at GitHub: <https://github.com/common-workflow-language>
-- Common Workflow Language at Wikipedia: <https://en.wikipedia.org/wiki/Common_Workflow_Language>
-- YAML.org: <http://yaml.org/> and YAML at Wikipedia: <https://en.wikipedia.org/wiki/YAML>
-- The CWL {{ cwl_version  }} Specification: {{ '<https://www.commonwl.org/{}/>'.format(cwl_version_text) }}
-- Workflow management system at Wikipedia: <https://en.wikipedia.org/wiki/Workflow_management_system>
+Continue reading the next sections of this User Guide!
+- [List of CWL Implementations](https://www.commonwl.org/implementations).
+- The [`common-workflow-language` organization](https://github.com/common-workflow-language) at GitHub.
+- [Common Workflow Language at Wikipedia](https://en.wikipedia.org/wiki/Common_Workflow_Language).
+- [YAML.org](http://yaml.org/) and [YAML at Wikipedia](https://en.wikipedia.org/wiki/YAML).
+- The {{'[CWL Specification VERSION](https://www.commonwl.org/VERSION)'.replace('VERSION', cwl_version_text) }}.
+- [Workflow management system at Wikipedia](https://en.wikipedia.org/wiki/Workflow_management_system).
 
 % N.B.: Wondering what's up with this syntax in the CWL Specification link above?
 % It's necessary as MyST Parser does not allow substitutions in links, for more:
diff --git a/src/topics/custom-types.md b/src/topics/custom-types.md
index 38bbcc1f..f0b59caf 100644
--- a/src/topics/custom-types.md
+++ b/src/topics/custom-types.md
@@ -21,7 +21,7 @@ converting a standard biom table file to hd5 format.
 :name: custom-types.yml
 ```
 
-___Note:___ To follow the example below, you need to download the example input file, *rich_sparse_otu_table.biom*. The file is available from <https://github.com/common-workflow-language/user_guide/raw/main/src/_includes/cwl/custom-types/rich_sparse_otu_table.biom>) and can be downloaded e.g. via `wget`:
+___Note:___ To follow the example below, you need to [download the example input file](https://raw.githubusercontent.com/common-workflow-language/user_guide/main/_includes/cwl/custom-types/rich_sparse_otu_table.biom), *rich_sparse_otu_table.biom* e.g. via `wget`:
 
 ```{code-block} console
 $ wget https://github.com/common-workflow-language/user_guide/raw/main/src/_includes/cwl/custom-types/rich_sparse_otu_table.biom
diff --git a/src/topics/file-formats.md b/src/topics/file-formats.md
index 2c6a572b..54dee779 100644
--- a/src/topics/file-formats.md
+++ b/src/topics/file-formats.md
@@ -8,8 +8,8 @@ type-checking when creating parameter files.
 For file formats, we recommend referencing existing ontologies (like EDAM in
 our example), reference a local ontology for your institution, or do not add
 a file format initially for quick development before sharing your tool with
-others. You can browse existing file format listings for IANA [here][IANA] and
-for EDAM [here][EDAM].
+others. You can browse existing [IANA file format listings][IANA] and
+[EDAM file format listings][EDAM] on their websites.
 
 In the next tutorial, we explain  the `$namespaces` and `$schemas` section of the
 document in greater detail, so don't worry about these for now.
diff --git a/src/topics/specifying-software-requirements.md b/src/topics/specifying-software-requirements.md
index 109090fb..c90a5ac5 100644
--- a/src/topics/specifying-software-requirements.md
+++ b/src/topics/specifying-software-requirements.md
@@ -31,8 +31,7 @@ given in the form of an [RRID][rrid]. Resources with RRIDs can be looked up in t
 [SciCrunch][scicrunch] registry, which provides a portal for finding, tracking,
 and referring to scientific resources consistently. If you want to specify a
 tool as a `SoftwareRequirement`, search for the tool on SciCrunch and use the
-RRID that it has been assigned in the registry. (Follow [this tutorial][scicrunch-add-tool]
-if you want to add a tool to SciCrunch.) You can use this RRID to refer
+RRID that it has been assigned in the registry. (Follow this [Adding a Resource Tutorial][scicrunch-add-tool] to add a tool to SciCrunch). You can use this RRID to refer
 to the tool (via [identifiers.org][identifiers]) in the `specs` field of your
 requirement description. Other good choices, in order of preference, are to
 include the DOI for the main tool citation and the URL to the tool.