docs: add an honest repository discoverability guide with metadata examples

Cerrado
  • ¿Algo no está bien?
#39 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Ya se ha fusionado un pull request relacionado.

  • #40 de @drevendev — fusionado

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
35/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Estancado
Stack tecnológico
github, markdown
Área
documentation

Línea de trabajo

Add guides/discoverability.md and link it from a sensible public handbook index. Start by reviewing the three cited primary sources and the README and handbook navigation; verify citation freshness, local links, and existing repository checks. Done means the guide includes concrete good and bad examples, accurate topic-selection rationale, a metadata verification checklist, and dated citations, with no repository settings changes; pull request #40 is already open.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Problem and source research

BeautifulRepo teaches reader-first repository presentation, but its handbook lacks a concise, practical explanation of repository discovery surfaces: About description, topic tags, optional homepage and social preview. This is distinct from #20, which tracks changing this repository's actual About settings (an owner-authorized administrative action). A source-backed research note dated 2026-10-07 identified the reusable teaching opportunity.

Scope

Publish guides/discoverability.md as a reader-facing maintenance recipe with:

  • Alignment between README's actual promise and a short repository description, including a good/bad example.
  • A restrained set of accurate GitHub topics, with an explicit warning against event/vanity tagging.
  • When a homepage and social preview help—and when an empty value is honest.
  • A no-cost verification checklist that uses publicly visible GitHub metadata, not stars, fictional traffic or external outreach.
  • Date-stamped primary citations and limitations: Open Source Guides, Finding Users, GitHub repository topics, and GitHub social previews.

Acceptance

  • Add concrete good/bad descriptions and topic-selection rationale, not just an external-links list.
  • Link from a sensible public handbook index without duplicating all README navigation.
  • Verify reference freshness at implementation time, test local links and existing repository checks.
  • Do not change repository settings, enable Pages, create a website, publish an announcement or imply permission to promote externally.

Related: #20 (repo metadata), #21 (evidence-first README), #33 (readiness acceptance). The guide itself is not an additional provider merge gate.

Lenguaje dominante
Python
Estrellas
2
Forks
0
Merge medio
3 h 40 min
PR fusionados (30 d)
174

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de drevendev/BeautifulRepo

Todos los issues de drevendev/BeautifulRepo

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.