canonical / canonical/robotics_documentation

Move the reference architecture page to Explanation

Open
#150 0 comments 0 reactions 0 assignees View on GitHub
CODA
Dominant language
No language data
Stars
1
Forks
5
Avg merge
14d 23h
Merged PRs (30d)
1

Description

The mentor for this issue is @geoffreynyaga

## Background

The Reference architecture page explains how parts of the Canonical Robotics stack fit together. Despite its name, it is explanatory content rather than reference material, so it belongs in the Explanation section under the Diátaxis documentation framework.

## Prerequisites

Basic Git and Markdown knowledge is required. Familiarity with Sphinx documentation is helpful.

## Task

1. In the [`canonical/robotics_documentation`](https://github.com/canonical/robotics_documentation) repository, move `docs/references/ref_architecture/reference_architecture.md` to the Explanation section. Move its image with it as well.
2. Remove the page from `docs/references/index.md` and add it to `docs/explanations/index.md`.
3. Update the home-page link in `docs/index.rst` and any other internal links to use the new path.
4. Add a redirect in `docs/conf.py` from the old URL to the new URL so existing links do not break.
5. Run `make clean` and `make linkcheck`; both commands must pass.
6. Open a pull request against the repository and sign the [Canonical contributor license agreement](https://ubuntu.com/legal/contributors).

## Outcome

The Reference architecture page appears under Explanation, no longer appears under Reference, and the former URL redirects to its new location. Internal links and link checking pass.

## Resources

* [Reference architecture source page](https://github.com/canonical/robotics_documentation/blob/main/docs/references/ref_architecture/reference_architecture.md)
* [Diátaxis: explanation](https://diataxis.fr/explanation/)
* [Diátaxis: reference](https://diataxis.fr/reference/)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with docs/references/ref_architecture/reference_architecture.md, its accompanying image, and the two documentation index files. Update docs/index.rst and other internal links, then inspect docs/conf.py for the redirect pattern. Run make clean and make linkcheck; done means the page is under Explanation, absent from Reference, the old URL redirects, and link checking passes.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, markdown
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.