Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[Lane 5 · docs] Precision/Recall/F1 — doc partials (math / intuition / examples / references)

Open
  • Is something wrong?
#1,234 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
Half a day
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Tech stack
kotlin, latex
Domain
documentation

Research direction

Start by reading docs/modules/ROOT/partials/ops/tensorops/matmul.adoc for the tag structure and the metrics how-to page for its existing example pattern. Create the three specified partials and include their tagged content in docs/modules/ROOT/pages/how-to/metrics-and-perf-testing.adoc; the examples tag depends on #1229. Build the site using the contributing guide or docs.yml workflow, and verify the math renders, the example compiles, and the reference links resolve.

Written by the indexing model from the issue text.

Description

documentation good first issue size:s skill:docs sub-issue

Sub-issue of #1222 (Precision, Recall and F1Score metrics).

Lane: 5 · Docs / DARC
Skill needed: AsciiDoc and technical writing; enough ML background to explain precision vs. recall. No Kotlin beyond reading a 30-line class.
Size: s (~2–3 h for all three)
Blocked by: nothing for the math / intuition / references tags (start now); the examples tag needs #1229 so the example actually runs.

What to do

  1. Write three partials, one per metric, following the tag structure of
    docs/modules/ROOT/partials/ops/tensorops/matmul.adoc:
    • docs/modules/ROOT/partials/ops/metrics/precision.adoc
    • docs/modules/ROOT/partials/ops/metrics/recall.adoc
    • docs/modules/ROOT/partials/ops/metrics/f1score.adoc
      Each with non-placeholder // tag::math[], // tag::intuition[], // tag::examples[],
      // tag::references[] blocks. Use stem:[…] / [stem] (LaTeX; the playbook sets
      stem: latexmath) for the formulas. The math block must state the per-class
      definition, what macro vs. micro averaging does, and the zero-division convention
      adopted in #1224.
  2. Metrics are not TensorOps functions, so the operator-doc generator will not pick
    these partials up automatically. Surface them by adding a "Precision, recall and F1"
    subsection to docs/modules/ROOT/pages/how-to/metrics-and-perf-testing.adoc that
    include::partial$ops/metrics/f1score.adoc[tag=intuition] (and the others by tag).
  3. The examples block must be real code that compiles against develop after #1229 —
    ideally a tagged snippet in skainet-docs-samples included via include::example$…,
    like the existing TrainingDemo.kt accuracy example on that page; a plain
    [source,kotlin] block is acceptable if you say why.
  4. Build the site locally (see Contributing → Build from source / the docs.yml
    workflow) and check the math renders.

Acceptance

  • Three partials, all four tags non-empty, math renders
  • Metrics how-to page shows the new section with the intuition text and a runnable example
  • Every reference link resolves and supports the claim next to it (the reviewer in
    #1235 will click each one)

Notes

Intuition to convey: precision answers "of what I predicted positive, how much was right";
recall answers "of what was actually positive, how much did I catch"; F1 is their harmonic
mean, so it punishes a classifier that is high on one only because the other is near zero —
which is exactly where raw accuracy stays silent (predict the majority class everywhere:
high accuracy, near-zero minority recall). Also spell out that macro F1 is the mean of
per-class F1s, not the F1 of the macro means.

References to start from: sklearn precision_recall_fscore_support, torchmetrics
F1Score, and https://en.wikipedia.org/wiki/F-score .

Dominant language
Kotlin
Stars
52
Forks
15
Avg merge
1d 4h
Merged PRs (30d)
37

Getting set up

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.

More from SKaiNET-developers/SKaiNET

All issues in SKaiNET-developers/SKaiNET

Similar issues

More Kotlin issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.