lablup / lablup/mlxcel

docs(reports): add an index README for the 308-file TECHNICAL_REPORTS directory

Open Beginner friendly
#1,708 0 comments 0 reactions 0 assignees View on GitHub
priority:low status:ready type:docs
Dominant language
Rust
Stars
467
Forks
54
Avg merge
4h 25m
Merged PRs (30d)
310

Description

## Summary

`TECHNICAL_REPORTS/` holds 308 files (154 en/ko report pairs) with no index, and is referenced from nowhere in the repo. The repo's own convention says it should have one: `docs/adr/README.md` is a complete index of the ADRs.

## Background

Without an index or any inbound link, a contributor cannot discover the reports or map an issue number to its report. The ADR directory already models the fix.

## Proposed Solution

Add `TECHNICAL_REPORTS/README.md` with a table (issue number, title, date, en/ko links) derivable mechanically from the filenames, plus a one-line pointer from `docs/README.md`. Scope: index only, no prose rewrites.

## Implementation Notes

- `ls TECHNICAL_REPORTS/*.md | wc -l` returns 308 (confirmed); no `README.md`/`index.md` in the directory (confirmed).
- `grep -rn "TECHNICAL_REPORTS" README.md CONTRIBUTING.md docs/*.md Makefile .github/` returns no matches; `docs/README.md` enumerates all docs pages and `adr/` but never this directory.
- Contrast `docs/adr/README.md`, the maintained ADR index.
- The reports themselves are healthy (spot-checked internal file refs in the newest reports resolve).

## Acceptance Criteria

- [ ] The index lists every report pair with working links.
- [ ] `docs/README.md` points at the directory.

---

## Original Suggestion

### Title: docs(reports): add an index README for the 308-file TECHNICAL_REPORTS directory

`TECHNICAL_REPORTS/` holds 308 files (154 en/ko report pairs, issues 916 through 1623) with no index, and is referenced from nowhere in the repo — not the README, not CONTRIBUTING, not the docs index. The repo's own convention says this should have one: `docs/adr/README.md` is a complete index of the five ADRs.

## Evidence

- `ls TECHNICAL_REPORTS/*.md | wc -l` → 308; no `README.md`/`index.md` in the directory
- `grep -rn "TECHNICAL_REPORTS" README.md CONTRIBUTING.md docs/*.md Makefile .github/` → no matches; `docs/README.md` enumerates all 23 docs pages and `adr/` but never this directory
- Contrast `docs/adr/README.md:1-11` — the maintained ADR index

(The reports themselves are healthy: 20/20 spot-checked internal file refs in the newest three reports resolve.)

## Suggested fix

Add `TECHNICAL_REPORTS/README.md` with a table (issue number, title, date, en/ko links) — derivable mechanically from the filenames — plus a one-line pointer from `docs/README.md`. Scope: index only, no prose rewrites.

## Acceptance criteria

- [ ] The index lists every report pair with working links
- [ ] `docs/README.md` points at the directory

Contributor guide

Open the contributing guide

Research direction

Use docs/adr/README.md as the indexing model, then inspect the filenames in TECHNICAL_REPORTS/ and docs/README.md. Run ls TECHNICAL_REPORTS/*.md and verify the generated table contains all 154 en/ko pairs with working links. Done means TECHNICAL_REPORTS/README.md indexes every report pair and docs/README.md links to the directory.

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
Active
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.