getodk / getodk/docs

Add style guideline about anchor text

Open
#554 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
58
Forks
160
Avg merge
5d 11h
Merged PRs (30d)
12

Description

Not preferred:

```
Do the thing :ref:`on the settings menu `.
```

Preferred:

```
:ref:`Do the thing `.

If context is needed:

:ref:`Do the thing ` on the :ref:`settings menu `.
```

Not prefered:

```
You can do a thing. `Learn more in this tutorial. `_.
```

Prefered:

```
`You can do a thing `_.
```

------

(Actual style guide should use realish examples, not "do a thing".)

Guidance should probably mention that it isn't *always* reasonable to follow this rule,
but to do so whenever you can.

Contributor guide

Open the contributing guide

Research direction

Locate the actual style guide in the documentation and review any existing guidance about anchor or link text first. Add real examples covering the preferred patterns and note that the rule is flexible when needed; the work is done when the guidance is clear and examples reflect the issue's recommendations.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.