Make developer documentation more discoverable and organized
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
- Domain
- developer-experience, documentation
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
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.mdthere in its entirety, to be the first occupant of that section. - Move all the material in
README.mdwhich 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from python/mypy
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
bug topic-configuration topic-error-reporting
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
bancolombia/sentinel#23 ·
-
test md OpenCI
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
-
integration:quickjs org:external priority:backlog topic:code-interpreter topic:middleware type:feature
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
langchain-ai/deepagents#6450 ·
-
bug client
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100