NatLabRockies / NatLabRockies/H2Integrate

Standardize example references in docs descriptions

Open
#876 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
26
Forks
44
Avg merge
3d 22h
Merged PRs (30d)
16

Description

Sometimes the docs get out of date because they are referenced in the docs page for a specific capability (i.e. the driver config usage) and then refers to a specific example (e.g. Example 5) to see how it's implemented. Then, somewhere down the line, Example 5 is updated/changed and the docs page isn't because it's hard to know where in the docs this capability was referenced.

We propose implementing a standardized way to refer to examples in the docs pages (i.e. Example 5, etc.) so that when you are changing an example, you can just search "Example 5" and see if/where it's referenced in the docs.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by searching the documentation for references such as “Example 5” and compare them with the examples they describe. Define a consistent reference format across the affected docs, then verify that changing an example makes all references discoverable through the standardized wording.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.