Skip to content
This repository has been archived by the owner on Dec 11, 2024. It is now read-only.

Convert tags in Gauge to labels in Confluence? #2

Open
johnboyes opened this issue Apr 3, 2021 · 0 comments
Open

Convert tags in Gauge to labels in Confluence? #2

johnboyes opened this issue Apr 3, 2021 · 0 comments
Labels
enhancement New feature or request

Comments

@johnboyes
Copy link
Contributor

johnboyes commented Apr 3, 2021

This could be useful to aid navigation of the specifications in Confluence.

Excerpt from the Specification by Example book by Gojko Adzic:

Use tags instead of URLs when referring to executable specifications: When: You need traceability of specifications

Many living documentation tools now support tags - freeform textual attributes that we can assign to any page or file. Metadata like this is generally better for traceability than for keeping specifications in a hierarchy by user stories or use cases. When the domain model changes, the living documentation should ideally follow those changes. Specifications will often get moved, merged, split, or changed. This is impossible if you rely on a strict static hierarchy for traceability, but it can easily be done if story/case numbers are assigned to specifications as tags.

Tags are also useful if you want to refer to a living documentation page from another tool, for example, from an issue-tracking-system ticket or a planning-tool schedule. Using a URL based on the current location of a page would prevent us from moving it later because the link would be broken.

Assigning a tag and linking to search results for that tag makes the system much more resilient to future changes.

Even if you don’t use a web-based tool and instead keep specifications in the project directory, you can still use tags with the help of a simple script. This is what the Norwegian Dairy Herd Recording System team at Bekk Consulting did. Børge Lotre explains this approach:

"To share Cucumber tests with customers we use Confluence and link the Cucumber tests directly from Subversion into Confluence. This prevents us from restructuring the file hierarchy of the Cucumber tests without hassle, but utilizing tags has proven to help us overcome this shortcoming."

“Now we use tags to document which requirements are covered by which Cucumber tests.”

Avoid referring to a particular specification in the living documentation system directly, because that prevents you from reorganizing the documentation later. Metadata, tags, or keywords that you can dynamically search for are much better for external links.

Labels documentation:

@johnboyes johnboyes added the enhancement New feature or request label Aug 16, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant