mimir icon indicating copy to clipboard operation
mimir copied to clipboard

Docs: Change task topic titles from gerunds to imperatives

Open chri2547 opened this issue 3 years ago • 7 comments

Change all task topics to (imperative) verb + object instead of using gerunds.

General approach:

  1. Add an alias that is self-referencing to all files.
  2. Commit the changes.
  3. Run doc-validator locally; leave global link checking for later.
  4. Commit the changes.
  5. Move a directory of files from -ing ending to imperative.
  6. Rerun doc-validator locally on that directory; leave global link checking for later.
  7. Fix any broken links with mv-manager.
  8. Rerun doc-validator from .../doc/sources in the mimir repo.
  9. Repeat as needed.
  10. Commit the changes.

chri2547 avatar Apr 08 '22 13:04 chri2547

This involves link checking and alias changes.

osg-grafana avatar Jun 29 '22 13:06 osg-grafana

Moving to 2.3 per conversation with @dimitarvdimitrov, because these changes are forward-facing changes and it reduces the need to cherry pick for 2.2.

osg-grafana avatar Jul 11 '22 10:07 osg-grafana

Per @pracucci, the paths that are now absolute need to be relative.

osg-grafana avatar Jul 15 '22 10:07 osg-grafana

Increasing estimate of complexity of this issue.

osg-grafana avatar Jul 15 '22 10:07 osg-grafana

Increasing estimate of complexity of this issue.

No. It's not a requirement. Aliases can both be absolute or relative (both are supported). There are pros and cons of both. The reason why I opened https://github.com/grafana/mimir/pull/2396 is because in https://github.com/grafana/mimir/pull/2351 the relative paths were rewritten adding a / in front of them (so making them absolute, but without changing them to be real absolute paths).

pracucci avatar Jul 15 '22 12:07 pracucci

@KMiller-Grafana, here is an issue that might cause problems with links breaking. @gguillotte-grafana is investigating how we can get visibility about which links are broken where across all Grafana Labs documentation. cc @knylander-grafana and @Eve832

osg-grafana avatar Aug 01 '22 16:08 osg-grafana

@pracucci is correct. The relrefs will still work either way, but it's not a good habit. I think if we're linking across repos, we can either use ref instead of relref or absolute URLs.

Eve832 avatar Aug 08 '22 17:08 Eve832

@colega, added you as assignee because you volunteered. :)

osg-grafana avatar Oct 26 '22 09:10 osg-grafana