vmware-tanzu/cartographer

Language on the Templates page is ambiguous

Open

#884 opened on Jun 1, 2022

View on GitHubContributor guide
 (1 comment) (0 reactions) (0 assignees)Go (64 forks)auto 404
documentationgood first issue

Repository metrics

Stars
 (452 stars)
PR merge metrics
 (PR metrics pending)

Description

On Page: Templates

On the Templates page (https://cartographer.sh/docs/v0.3.0/reference/template/#clustersourcetemplate)

ClusterSourceTemplate starts out with:

indicates how the supply chain could instantiate an object responsible for.....

And other resources down the page (for example, ClusterImageTemplate start with:

instructs how the supply chain should instantiate an object responsible for

It's

could instantiate

vs

should instantiate

I read the word "could", and I think "well, are there other ways?" I read the word "should", and I think "ah, this is how the contract is fulfilled".

Honestly, I think it can be fixed by simply dropping should/could. So for example, the new language for ClusterSourceTemplate would read:

ClusterSourceTemplate instructs the supply chain to instantiate an object responsible for providing source code.

I'm open to thoughts/discussions, though!

Contributor guide

Research direction
Review the Templates documentation page and identify all instances of 'could' and 'should' in the descriptions of ClusterSourceTemplate and ClusterImageTemplate. Propose consistent language that removes ambiguity, such as using 'instructs the supply chain to instantiate' instead of 'could/should instantiate'. Update the relevant markdown files.
Tech stack
go
Domain
documentationbackend
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
Under 1 hour
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
GitGo
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
85