Make developer documentation more discoverable and organized

Open
#3,407 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
git, github, markdown

Research direction

Start by reviewing the existing ReadTheDocs setup and the listed files: test-data/unit/README.md, README.md, CONTRIBUTING.md, and the wiki. Define the developer-documentation section and identify relevant material to move, preserving the existing content. Done means developer docs are navigable on ReadTheDocs and obsolete wiki material is removed.

Written by the indexing model from the issue text.

Description

documentation topic-developer topic-usability

We have something over 3000 words of developer documentation, spread across several files:

$ git ls-files | grep -e README -e md$ | xargs wc -w | sort -rn
 3413 total
 1052 test-data/unit/README.md
 1015 README.md
 1005 CONTRIBUTING.md
  181 pinfer/README
  139 docs/README.md
   21 extensions/README.md

The top-level README has gotten long enough that it's easy to miss things there, which motivated us to split out the discussion of how tests work into a separate tests README. That discussion has grown with a lot of useful content and is also getting long -- and at the same time, because it was split out it's become easy for people to miss that it exists in the first place and that they should read it, as there isn't any significant cross-file navigation available for README files displayed on GitHub.

Zulip has adopted a model of writing developer documentation to display on readthedocs, in the same way as their user documentation. The greater navigation structure available there helps a lot in letting the documentation scale to being readable across a number of files totalling much more information in total -- the model seems to scale pretty well.

Since we already have documentation set up on readthedocs, and our developer documentation is already also in Markdown, I think it should be pretty easy to move our developer documentation there and that will help us out. I'd approach it something like this:

  • Make a section in the Mypy docs for Mypy development documentation. Move test-data/unit/README.md there in its entirety, to be the first occupant of that section.
  • Move all the material in README.md which is only relevant when developing mypy itself into another file or two in that section. For example "Quick start for contributing to mypy" and "Working with the git version of mypy", and some small pieces of other sections.
  • Go through the wiki, move everything still relevant to those docs (if developer-facing, or elsewhere if not), and delete the rest.
Dominant language
Python
Stars
20.6k
Forks
3.3k
Avg merge
1d 18h
Merged PRs (30d)
54

Contributor guide

Open the contributing guide

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 python/mypy

All issues in python/mypy

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.