Jacob Kaplan-Moss

> the best way to do that would be to make tools that make beautiful documentation easy.

Really? I find it hard to believe that the problem is caused by a lack of tools. Clojure already has five or six tools for spitting out a programmatically-generated HTML overview of the shape a given project.

Instead I think it's clear the reason this doesn't happen is that good documentation is really difficult to write and people don't want to put the necessary effort into it. Putting aside the obvious problem that good English prose is really difficult to write, you have to overcome the fact that the people qualified to write the documentation don't much benefit from it. On top of that, it's very difficult for an experienced user to put himself in the mindset of a beginner.

In fact, I'd go so far as to say that the existence of all this existing documentation tooling only goes to reinforce the harmful notion you can just run something like marginalia over your codebase and publish the HTML output somewhere and consider your project documented. Sure, API overviews are valuable as a reference, but they're mostly just a distraction to someone starting out who just wants to figure out whether the project is a good fit for their needs. Long-form prose documentation is crucial at that stage, and it's awfully hard to come by.

http://jacobian.org/writing/great-documentation/what-to-write/

Anyway the tooling is trivial--getting an overview of the API and docstrings has been done over and…

hi marjin! thanks again for all your work on prosemirror. the docs are quite thorough (and have gotten moreso in the past few months!), but a specific thing which i ended up needing to dive into the code for was something like setting up a custom menubar[1] with a menugroup.

The docs back then (and even now) do this thing where they get rapidly tautological and have you hop around between type definitions but don't, for instance, show you what the default `menuBar`'s content value is, in terms of a MenuGroup so it's not readily obvious how to customize my own without reading the source.

So reading the docs, while i can certainly find out what things are and how they connect, i don't have a good sense of what decisions prosemirror made for me (or how it made them) so that i can intentionally customize or integrate in a non-backwards way. If the code weren't so legible, this would be a massive problem, but it's the sort of in-depth documentation that needs somebody working strictly on documentation in that way that kaplan-moss talks about[2]. I totally get that prosemirror is early days and integrating it has been a good experience, but that's the sort of documentation pain-point i was referring to. Thanks again!

[1]: http://prosemirror.net/ref.html#menu/menubar
[2]: https://jacobian.org/writing/great-documentation/

From good colleagues
- Be someone that improves your environment whatever you're put into - code, team dynamics, communication whatever.
- Be relentless in pursuing something that you're convinced is worthwhile. Things and times change. If you feel something is good for you and the org, do it. Don't waste time "thinking".
- Orgs have reputation inflation. If you're the same as you were last year/month/week, you've actually dropped.
- Demand results and reward when you get them. Keep pushing your reports
- Be consistent and be present.
- Leadership is revealed during crises. Be in control when shit hits the fan.
- Identify exceptional skills in your reports, sell those to the higher level organisation.

From bad colleagues
- Protect your direct reports from the organisation (politics, snatching away of bonuses etc.)
- Junior reports cannot function without a clear task. You need to handle the org and make sure they get it. (this was summarised in a great article - "context down, information up" - https://jacobian.org/2021/apr/19/the-fundamental-purpose-of-middle-management/)
- Respect everyone and mentor juniors who look up to you.
- Don't accept leadership positions if you can't actively play office politics.

This is a great article.

One thing I would add to this is that nobody really knows what licenses like the GPL actually do. Jacob Kaplan-Moss published a fantastic piece called "20 questions about the GPL"[0] , and my attempts to clarify a few of them with the FSF and SFLC have so far revealed that not even two developer advocate organizations can agree on even fundamentally basic concepts about the most popular license, so isn't that a problem?

The reason that I contribute to the "projects on GitHub with no license" problem is that I cannot find a license that unambiguously does what I want, after spending many, many weekends on the problem. I could write one, or get my lawyer to, but license proliferation is grounds for expulsion from the cool kids club. Since I have no good options, I take no action.

Fundamentally, I believe we need a new license steward that isn't afraid to update regularly to address 1990s questions like dynamic linking and optional dependencies, and 2010s questions like app stores. Something like Creative Commons for code, where you have some options to choose from.

[0] http://jacobian.org/writing/gpl-questions/

Great initiative, but beware relying on automatically generated documentation. Keep units documented in the code, and have your higher-level docs handwritten and hand-structured elsewhere, is the policy I’ve arrived at lately.

(It doesn’t make sense to spend resources on having units documented separately from code, because you don’t need such docs unless you’re working with code. Loads of auto-generated docs also gives a false impression of your project being properly documented, which it isn’t unless you also have higher-level hand-written documentation somewhere.

Similarly, it doesn’t make sense to keep high-level architecture docs in docstrings, as it’s not tied to specific modules, and you normally need it when you’re thinking big picture as opposed to working with specific code units.)

Overall, kudos—good documentation is important.

If you’re concerned about writing good documentation, I recommend reading these series by Jacob Kaplan-Moss (of Django core development team): https://jacobian.org/writing/great-documentation/

It does work with pyenv, but can be slightly tricky. I used a setup recommended by Jacob Kaplan [1] that uses pyenv, pipx and poetry.

Pyenv is used to manage different versions of Python and virtual environments (using pyenv-virtualenv [2]). Pipx will be accessible only from the python version or virtual environment it is installed to. However, the programs that you install using pipx (like gita or poetry) have their own virtual environments, and run reliably irrespective of accessibility of pipx and what you have activated using pyenv.

It's easier to install pipx into the pyenv python version that you have set up as global. This ensures that you have access to pipx most of the time. You could just spawn a temporary shell with global python to access pipx otherwise.

[1] https://jacobian.org/2019/nov/11/python-environment-2020/
[2] https://github.com/pyenv/pyenv-virtualenv