The quality of my work ticked up materially when I set myself a policy of bundling the documentation updates in the same commit as my implementation and tests
Personal definition of success:
Your job, as a human, is to find whatever it is that you're passionate about
to do it, full throttle–without hurting anyone in the process
and to always leave people, places, & projects significantly better than you found them.
...That is all.
It's been a while since I made mktestdocs but it's still such a joy to use. The code snippets in the docstrings of many of my packages are guaranteed to work because they are also a unit test.
https://github.com/koaning/mktestdocs
📊 Is anyone else super dissatisfied with the tech industry's preferred/tracked open-source metrics?
@GitHub stars; pip install or download counts; @-mentions or tags on social media: all of these stats can, and will, be gamed. We can do much better!
👇🏻Here are some ideas:
(1) Projects listing a particular repo as a dependency.
This can be easily tracked via GitHub's dependency graph, or by scraping which Dockerfiles, conda environment YAMLs, etc. reference a library or framework.
(2) "Bus factor" of a particular open-source project.
Bus factors measure how resilient a project is to sudden engineering turnover - and is a solid method of understanding the health of an open-source project.
More on bus factors below:
📄https://arxiv.org/abs/2202.01523
(3) General insights into code health:
What is the test coverage like for the open-source project? Are there any code quality concerns? To what extent?
✨📝 "We propose a single framework to identify several categories of code quality issues that can cause low code readability and maintainability.
We also developed an automated tool that spots large numbers of such issues in open-source repositories."
👩💻 Paige Bailey #BlackLivesMatter @DynamicWebPaige · Nov 14 📊 Is anyone else super dissatisfied with the tech industry's preferred/tracked open-source metrics?
@GitHub stars; pip install or download counts; @-mentions or tags on social media: all of these stats can, and will, be gamed. We can do much better!
👇🏻Here are some ideas: 👩💻 Paige Bailey #BlackLivesMatter @DynamicWebPaige · Nov 14 (1) Projects listing a particular repo as a dependency.
This can be easily tracked via GitHub's dependency graph, or by scraping which Dockerfiles, conda environment YAMLs, etc. reference a library or framework. Image 👩💻 Paige Bailey #BlackLivesMatter @DynamicWebPaige · Nov 14 (2) "Bus factor" of a particular open-source project.
Bus factors measure how resilient a project is to sudden engineering turnover - and is a solid method of understanding the health of an open-source project.
More on bus factors below:
📄https://arxiv.org/abs/2202.01523 Image 👩💻 Paige Bailey #BlackLivesMatter @DynamicWebPaige · Nov 14 (3) General insights into code health:
What is the test coverage like for the open-source project? Are there any code quality concerns? To what extent? This Tweet is unavailable. Learn more 👩💻 Paige Bailey #BlackLivesMatter @DynamicWebPaige (4) On a similar vein:
What is the documentation coverage like for each feature? This should include everything from function docstrings, to guides and tutorials.
And are there 'vignettes' (end-to-end examples, stitching together multiple features)?
📃 Documentation is a developer's first impression of your project—and great docs show a commitment to empathy+respect: welcoming people wherever they are, and patiently helping them move to the next level.
Docs are such a powerful way to care for users, to build a community.
(5) Do one or more companies depend on the open-source project for their core business?
And, if yes: are engineers at those companies contributing back to the project + upstreaming changes, or have they forked the codebase and kept it closed-source?
(6) For machine learning & research libraries:
Of recent papers that have released source code, how many of those papers import or use your tool? How has that # changed over time?
Do you observe that a given framework or library is preferred for a specific use case/domain?
Learn pytest, in particular learn how to use parameterized tests and pytest fixtures. Biggest improvement I've made to my testing abilities in my entire career
Wrote a bit about those here:
https://simonwillison.net/2018/Jul/28/documentation-unit-tests/
I gave a talk last week on how to be your biggest advocate so you can work more efficiently towards promotions. One thing I pushed in this talk is having a progress doc, so I wanted to share how I have organized mine and how I maintain it. Hopefully it'll help you in some way!
First/Title Page: On this page I will have different headers for:
Subsequent Pages: Starting from my first month, I organize this doc in 6-month periods. Under each time-period I have it organized into different subcategories. The main subcategory in each section is "Engineering" but other sections may include any other broader org initiatives.
My favorite RFCs & feature requests include:
What is it? (2-3 sentences) Who is it for? Why is it needed?
When would (and wouldn't) I use it? How does it compare to existing solutions?
What is the anticipated maintenance burden? What portions of the API surface does it touch?
Two quotes I'll be putting on my wall from @PyTorch in this article:
"A library needs to deliver compelling performance but not at the expense of ease of use. You can trade 10% speed, but not 100% speed, for a significantly simpler to use library." 1/2
And, arguably my favorite of the two
"It’s better to have a simple but slightly incomplete solution than a comprehensive but hard-to-maintain design."
