Skip to content

Audit and improve markdown file naming conventions #87

@AndrewBMadison

Description

@AndrewBMadison

Problem

Multiple markdown files across the repo use generic names like README.md, making them hard to distinguish in editor tabs, search results, and file listings. There's no consistent naming convention for documentation files.

Examples

  • starters/beginner/README.md, starters/intermediate/README.md, starters/llm/README.md — all show as "README.md" in tabs
  • docs/ has a mix of styles: new_architecture.md, issue_60_ldx_refactor_plan.md, learner_developer_experience.md, dev_tools.md
  • Some docs are implementation plans/summaries that may not belong as permanent documentation

Scope

This is an open-ended housekeeping issue. Possible actions include:

  • Decide on a naming convention for starter docs (e.g., GUIDE.md, getting_started.md, or keep README.md)
  • Audit docs/ for files that are implementation artifacts vs. actual documentation
  • Archive or remove stale planning docs (e.g., issue_60_ldx_refactor_plan.md, ldx_refactor_implementation_summary.md)
  • Establish a naming convention for new docs going forward
  • Update any internal references if files are renamed

Notes

Low priority — pick this up when doing a docs cleanup pass. The starter README.md files have a valid argument for keeping the name (GitHub auto-renders them, users expect the convention), so this should be a deliberate decision, not a blanket rename.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    Status

    Backlog

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions