apaz-cli
diff --git a/‎blog/The_Contributor_Competition-unstyled.html
+84-102 b/‎blog/The_Contributor_Competition-unstyled.html
+84-102
@@ -7,89 +7,67 @@
   <title>The Contributor Competition</title>
 </head>
 <body>
-<h1 id="the-contributor-competition">The Contributor Competition</h1>
+<h1 id="the-open-source-contributor-competition">The Open Source
+Contributor Competition</h1>
 <p><br></p>
 <div style="text-align: center;">
-<p><img src="images/ruin_sword.jpg" /></p>
+<p><img src="images/Ibuki_Maya.png" /></p>
 </div>
 <h4
-id="open-source-projects-compete-for-contributors.-how-can-you-make-your-project-win">Open
-source projects compete for contributors. How can you make your project
-win?</h4>
+id="open-source-maintainers-compete-for-contributors.-how-can-you-win">Open
+source maintainers compete for contributors. How can you win?</h4>
 <h2 id="a-case-study.">A case study.</h2>
 <hr>
 <p>    Python and Julia are programming languages that fill a very
 similar niche. They're both dynamic scripting languages popular in the
 scientific computing space. Why is Julia languishing, while Python is
 flourishing?</p>
-<br>
-<div style="text-align: center;">
-<p><img src="images/Python_vs_Julia.png" /></p>
-</div>
-<p><br></p>
-<p>    Julia has been relatively successful at attracting users. A lot
-of CS students learn Julia in college. But very few have been convinced
-to become contributors. I was curious, so I looked at the recent PRs. I
-was looking for a PR from someone not in the Julia programming language
-organization. I found one. It was the 63rd PR I looked at. A prolific
-contributor who wasn't technically in the organization, but had
-contributed all over the Julia package ecosystem. I scrolled through a
-couple more pages, but couldn't find a name that I didn't recognize. The
-Julia community is very tight-knit and insular.</p>
-<p>    I did the same for Python. The fourth PR from the top was
-submitted by a first time contributor. The Julia organization on Github
-has 187 members. Python has by far more users, but only 129 members.
-Anyway, this is circumstantial evidence that doesn't prove anything. But
-something is going on here.</p>
 <p>    No language is "better" than another. Usually these comparisons
-are an excercise in tribalism. But bear with me here. Let's look at just
-the technology. In a vaccum, Julia seems "better" than Python.</p>
-<p>    It's faster. It automatically deduces types, then uses them to
-jit compile using LLVM ORC. You can compile a function and read the
-assembly. It has perhaps (tied with ipython) the best REPL in the world,
-built into the base language. It solves the <a
-href="https://en.wikipedia.org/wiki/Expression_problem">expression
-problem</a>, which python cannot. It has a more principled package
-manager. You can run Julia code on the GPU. The compiler is extensible.
-Very fancy. It's a complex and incredible marvel of engineering. It has
-everything going for it, from a technical perspective, minus the
-maintainability issues.</p>
-<p>    Why, then, does Julia not attract contributors? Surely all of
-that should make people want to work on it, right?</p>
+are an exercise in tribalism. But bear with me here. Let's look at just
+the technology. In a vacuum, Julia seems overwhelmingly "better" than
+Python. It's a complex and incredible marvel of engineering. It has
+everything going for it, from a technical perspective. Why, then, does
+Julia not attract any new contributors? Surely all of that should make
+people want to work on it, right?</p>
 <p><br></p>
 <h2 id="the-problem">The Problem</h2>
 <hr>
-<p>    Yeah, no. None of that matters. You can have the fanciest
-compiler in the world. Nobody cares.</p>
+<p>    Yeah, no. None of that matters. We don't live in a vaccum. You
+can have the fanciest compiler in the world. Nobody cares.</p>
+<p>    Developer experience matters. More than enough to sink an entire
+project.</p>
 <p>    Fundamentally, what contributors want is to solve their own
 problems and optimize their own experience. They are selfish. They think
 about how to use the project to accomplish their own goals. They don't
 care about the maintainer's problems as much as the maintainer may hope.
 Especially if they cannot at a glance understand those problems.</p>
-<p>    Potential contributors may support your mission, but they won't
-sacrifice anything for it. Julia is too complicated to contribute to
-without sacrifice. I know because I have sacrificed. This is Julia's
-biggest problem.</p>
+<p>    Potential contributors may support your mission, but it's hard to
+make them sacrifice for it.</p>
 <p>    Contributors want to contribute so that they can avoid pain, not
-take on more pain. They also have a very short attention span. If they
-can't immediately solve their problem, they will leave. They'll find a
-workaround without upstreaming a fix, or they will just find some other
-project. The only way to get someone to sacrifice for your cause is to
-pay them, or offer some other incentive. Nobody wants to clean up your
-mess for you. Open sourcing your code is not going to change that.
-Nobody is going to materialize next to you with a solution.</p>
+take on more pain. They have a very short attention span. If they can't
+immediately solve their problem, they will leave. They'll find a
+workaround without upstreaming a fix, or just find some other project.
+Unless you can find a select few rare and ideologically motivated
+individuals, the only way to get contributors who will sacrifice for
+your cause is to pay them. Nobody wants to clean up your mess for you.
+Open sourcing your code is not going to change that. Nobody is going to
+materialize next to you with a solution.</p>
 <p>    I've had multiple conversations with maintainers to the effect of
 "We have a long list of good first issues, why is nobody picking them
 up? We have like three hundred of them! Fix our type inference bugs!
 Debug our segfaults! Why are there no new contributors? They should be
 cleaning up after us!"</p>
-<p>They forget that people have their own problems to deal with.</p>
+<p>    They forget that non-ideologues have their own problems to deal
+with.</p>
 <p><br></p>
 <h2 id="the-solution">The Solution</h2>
 <hr>
-<p>    For an open source contributor, the decision to contribute or not
-is a simple risk vs reward. The risk is wasted time. The reward is
-getting features and fixes merged.</p>
+<p>    This requires a paradigm shift. For an open source contributor,
+the decision to contribute or not is a simple risk vs reward. The risk
+is wasted time. The reward is getting features and fixes merged. In this
+way, it's a lot like a startup product. The more annoying the
+experience, the more users and contributors will churn. But get it
+right, and you could experience explosive growth.</p>
 <p>    To maximize external contributions, maintainers need to
 drastically lower the barrier to entry while making the project as
 useful as possible. That way people are drawn to the project, and useful
@@ -100,69 +78,73 @@ <h2 id="the-solution">The Solution</h2>
 features with, who can review your code and point out conceptual
 issues.</p>
 <p>    In addition to lowering the barrier to entry, You need to make
-sure that people know it's low. Otherwise they will make a subconcious
-error in their risk/reward analysis. Frequent communication is key for
-this. If they see people on discord asking how a feature works, they
-know that if they write a PR, if they encounter issues they can ask
-questions as well. Then they will go do that. But if you need to find
-someone willing to review your PR and you haven't already befriended a
-maintainer, and you're not sure that the code will be readable in the
-first place, then maybe not. Your time is probably better spent
-elsewhere.</p>
-<p>    "Low attention span" describes most first time contributors, but
-there do exist other kinds. The other kind is a contributor with a
-difficult problem and some determination. They want to use your project
-to do something, something it may not even be designed for. And they
-need your help. These people are great. Empower them as much as you
-can.</p>
+sure people know it's low. Otherwise they may make a subconscious error
+in their risk/reward analysis and not contribute, to the detriment of
+all parties. Advertising good developer experience is helpful in
+advertising the project, but even more helpful for the maintinence of
+the project.</p>
 <p><br></p>
 <h2 id="actionable-advice.">Actionable Advice.</h2>
 <hr>
 <p>This is all well and good. But it's not actionable advice. Here is
 some actionable advice.</p>
 <p><br></p>
 <ol type="1">
-<li><p>Automated testing is a must. Write good, exhaustive tests so that
-contributors can be confident that their features and fixes won't cause
-regressions elsewhere. Equally important, write up a guide on how run
-tests and add tests, and place this guide somewhere prominent. Both
-should be as frictionless as possible.</p></li>
+<li><p>Automated testing is a must. Write good, exhaustive tests that
+don't flake so that contributors can be confident that their features
+and fixes won't cause regressions elsewhere. Prioritize integration
+tests. Equally important, write up a guide on how to add tests and run
+them, and place it somewhere prominent. Both processes should be as
+frictionless as possible.</p></li>
 <li><p>Document anything that would not be immediately understandable by
-a layperson. As a Julia example, nobody without a degree in compiler
-engineering is going to understand what a phi node or a dominance
-frontier is. It's core knowledge for understanding how Julia works, but
-that doesn't matter. If you want contributors, then this is
-unacceptable. It needs to be documented and made simple. At very least,
-point to resources that can be consumed in &lt; 15 minutes. If it
-doesn't exist, then write it yourself. No single problem is so
-complicated that it should take more than 15 minutes to explain. If it
-does, the explanation can probably be broken up.</p></li>
+a layperson. As a Julia/LLVM example, nobody without a degree in
+compiler engineering is going to understand what a phi node is. It's
+core knowledge for understanding how Julia works, but that doesn't
+matter. You can't expect people to have this knowledge when they start
+reading your code. If you want contributors, then this is unacceptable.
+It needs to be documented and made simple.</p></li>
 <li><p>APIs should be self documenting, but you should document them
 anyway. Exhaustively. You can do this with LLMs, they're very good at
-it. If it's python, add type annotations. Not as a tool for
-communicating with a type checker, but as a rule for communicating with
-humans. It makes the code more readable. I find myself spending a long
+it. If it's python or another language with optional typing, add type
+annotations. Not as a tool for communicating with a type checker, but as
+a tool for communicating with humans. When they're absent, people spend
 time figuring out all the different places a function could be called
-from so that I can figure out types. The better solution is to just put
-them there yourself.</p></li>
-<li><p>Set up a Discord server. Most people don't have Slack, and people
-usually don't want to sign up for your Discourse. But I understand that
-those do work for some projects. Github discussions are a suitable
-alternative, but work best for single repo projects. Whatever you
-choose, be active there answering questions. Think of this time
-investment as an investment. More people will arrive later with the same
-question, and other people will know the answer. Maybe you'll even get
-your own <a
-href="https://discuss.pytorch.org/u/ptrblck/summary">ptrblk</a>.
-Distributing the knowledge is very important.</p></li>
+from. Don't annoy your contributors. Add type annotations.</p></li>
+<li><p>Set up a Discord server. Or a public slack, an IRC, a Discourse,
+or Github discussions, or whatever. Wherever your potential users are.
+It's usually Discord, but might be somewhere else. Then be active there
+answering questions. Think of this time as an investment. If people see
+discussions about features and PR, they know that if they write a PR and
+encounter issues they can ask questions there as well. Then they may go
+do that. It's also a good way to disseminate knowledge.</p></li>
 <li><p>Acknowledge and appreciate contributions. Doesn't matter how
 large or small. You want contributing to your project to feel good. Make
 sure they feel proud of their work. This too is an investment. The goal
 is to turn short term contributors into long term contributors.</p></li>
-<li><p>Create tutorials. If your project has a feature, then it needs a
-tutorial. These tutorials can also serve as marketing material.</p></li>
-<li><p>Office hours are incredibly useful.</p></li>
+<li><p>Create tutorials and examples. If your project has a feature it
+needs a tutorial or example. Otherwise nobody will know about it. These
+can also serve as very effective marketing material.</p></li>
+<li><p>Office hours can be incredibly useful. Voice and/or video
+communication is much higher bandwidth than text alone, making it the
+superior medium for feature design discussions. But why office hours
+specifically? It's possible to ask the relevant parties if they want to
+VC, but demanding that much time can be seen as daunting or rude. It's
+often better just to set a regular meeting time for discussions of any
+sort.</p></li>
+<li><p>Imagine yourself in the shoes of a new user and contributor.
+You're using the project for X, and you want to implement new feature Y.
+Where is it likely you would get stuck, if you were to use and read your
+code for the first time? Are all the places that would need to be
+changed intuitive and easy to find? How can you fix or document this? If
+you have willing contributors, use them as test subjects and solicit
+feedback on the experience. Not just the experience of using the
+project, also the experience of modifying it.</p></li>
+<li><p>Maintain a high bar for quality.</p></li>
 </ol>
 <p><br></p>
+<h2 id="conclusion">Conclusion</h2>
+<p>TLDR, empower your contributors.</p>
+<p>Identify potential roadblocks and rip them out before they become a
+problem. things that might be holding them back. Remove roadblocks.</p>
 </body>
 </html>