Jacob Kaplan-Moss

http://jacobian.org is an excellent blog from one of the creators of Django framework – lots of good writing about engineering management, general team work and software development etc.

I’ve got one. When estimating tasks, there’s a particular blog article I like to reference [0] and I used an LLM to summarize it into a set of project instructions. Did it read the summary? Nope, I already know the material and have been using it for years. But it was a great way to communicate the key points to the model as part of project instructions. [0]: https://jacobian.org/2021/may/25/my-estimation-technique/

Jacob Kaplan-Moss gave a great talk at the last DjangoCon about money - what Django would do with an increased budget and how to get there: https://jacobian.org/2024/oct/8/dsf-one-million/ Video: https://www.youtube.com/watch?v=5nS1SSuHk9I

Here are my favorites: - Jacob Kaplan-Moss (https://jacobian.org/) [Engineering leadership, OSS] - Anton Zhiyanov (https://antonz.org/) [SQL, Go, Python] - Julia Evans (https://jvns.ca/) [SQL, Linux, Python, Go, Web] - Brandur Leach (https://brandur.org/) [Postgres, Go, Ruby, Web] - Brandon Rhodes (https://rhodesmill.org/brandon/) [Python, Astronomy, Linux] - Nathanial J Smith (https://vorpus.org/blog/) [Python, Async, Linguistics] I also write occasionally at https://rednafi.com.

This is a tech-focused selection from my personal list, with a few more business-y sources thrown in: - https://erikbern.com - https://lethain.com - https://commoncog.com - https://scattered-thoughts.net - https://danluu.com - https://ideolalia.com - https://staysaasy.com - https://collabfund.com - https://blog.nelhage.com - https://jacobian.org - https://equalventures.substack.com - https://defmacro.org - https://spakhm.com - https://apenwarr.ca - https://scarletink.com - https://benkuhn.net - https://cpojer.net - https://brandur.org - https://zeptonaut.com Let me know if you want some reading recommendations for any of these!

This is a great article with some valuable insights. I also noticed that it is part of a larger series of articles on Software Estimation which in my experience is one of the most challenging aspects of development in any organization. Worth reading: https://jacobian.org/series/estimation/

https://jacobian.org is Jacob Kaplan-Moss's website https://jacobin.com is a socialist magazine This blog post is from the former!

Staying somewhere too long is just as bad as job hopping. I've also seen a lot of developers who stayed in their job for a long period of time and were not very good at it, while the "job hoppers" were at the top of their game. One of the biggest challenges is that the interview process does not give an employee or an employer a good signal on if the relationship will be mutually beneficial and a good fit for both people. I've also seen a lot of companies that will present the environment etc. one way during the interview only to find that things are much different once you get into the day to day. Also, the followup article adds some more nuance to this here. https://jacobian.org/2022/oct/20/tenure-and-seniority/

This is just the first article in the series. I'd recommend reading all 4 articles before rebuking this one. https://jacobian.org/series/estimation/ For example, here's an except from the SWAG article: > The tradeoff is time: estimation techniques, including mine, require some time to produce any level of accuracy. > Sometimes, though, it’s less important that an estimate be accurate than that it be quick.

Here is the author's follow-up post on the topic: https://jacobian.org/2021/may/25/my-estimation-technique.

Some of the blogs I like, but don’t read enough (I almost ceased reading blogs at all lately): - https://jacobian.org/posts/ - https://www.kalzumeus.com/archive/ (classic) - https://schwitzsplinters.blogspot.com/

Love it, great work! One recommendation I have is Jacob Kaplan-Moss' blog: https://jacobian.org/index.xml

A lot of the origin of this work is from Jacob Kaplan-Moss who did the original refactor of the Django documentation. He wrote up the concepts here in 2009: https://jacobian.org/series/great-documentation/ Daniele Procida built on this and formalized it through this resource, which is really amazing and definitely the best resource for writing docs that I know of.

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

What I know about this is from 10 years ago. It's one of the "Twenty questions about the GPL" listed at https://jacobian.org/2009/jul/13/gpl-questions/ . One of the responses is at https://gist.github.com/Neurogami/146713 : > "Unfortunately all the FSF can provide on a number of these questions is their opinion on the matter. Having spoken with the Software Freedom Law Center about the import issue recently the reality is there is no answer to some of these questions because no one has ever taken them to court." The HN thread about those 20 questions is at https://news.ycombinator.com/item?id=702304 . My view is to follow the intent of GPLv3 and either make your package GPLv3 (though you can leave the copyright to your own code as MIT), or remove the GPLv3 package.

Also an absolutely fantastic article from Jacob Kablan-Moss, one of the three original founder of Django on REST anti-patterns (not Django specific at all): https://jacobian.org/writing/rest-worst-practices/ Every web developer should read that ^

Hey! I've got the following resources bookmarked: - https://jacobian.org/writing/great-documentation/ - http://ericholscher.com/blog/2014/feb/27/how-i-judge-documentation-qua… - examples: https://github.com/PharkMillups/beautiful-docs/blob/master/README.md - also checkout this heavybit video: http://www.heavybit.com/library/video/2014-12-09-jacob-kaplan-moss

Here's a really great resource on how to make your project accessible: http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-sou… If you only read one link from that page, make it this one: http://jacobian.org/writing/great-documentation Those two pages are well worth your time.

I think you're exactly correct, and "unlimited vacation" is almost always better for the company than the employee. Here's a great essay on the ills of a policy like this: http://jacobian.org/writing/unlimited-vacation/ One of the main issues it that the US is one of the few (maybe only?) industrialized nation that doesn't require companies to offer PTO: http://en.wikipedia.org/wiki/List_of_statutory_minimum_employment_leav…

Another great resource: http://jacobian.org/writing/great-documentation/

You need both (jacob Kaplan-Moss explained this pretty well: http://jacobian.org/writing/great-documentation/what-to-write) I find this kind of features is quite interesting, because API-doc is useful when you need a precise information ("I know there is a function for this, but what's the args order again ?"). When the only doc for a new project I am interested in is javadoc/doxygen, I usually run away.

It's probably safe to say that Django has hands-down the best documentation I've ever had the pleasure of using in an open-source project. No matter what you need, be it a step-by-step tutorial for first-timers, detailed documentation of every piece of the framework, low-level API docs for basically every function in the damn framework, or guides to writing your own reusable "apps" in Django, it's all right there on the project's website. Jacob Kaplan-Moss (one of the creators of Django) wrote a great series about documentation specifically at http://jacobian.org/writing/great-documentation/.

Jacob Kaplan-Moss recently wrote a series of really good articles about writing good documentation, I highly recommend reading them if you're about to embark on making technical docs: http://jacobian.org/writing/great-documentation/ He subdivides documentation as a whole into more or less the following three sections: - Tutorials - Topical Guides - Reference Screencasts can work for Tutorials, and they can be used for marketing purposes, in which they're closer to topical guides but probably won't provide as much depth as a textual guide could. Imho. a screencast can be great as a marketing tool, but not so much as a learning tool.

Your link is pointing to the article from 2007. Here's the followup he wrote yesterday titled "The Django community in 2009" http://jacobian.org/writing/django-community-2009/

I enjoyed recently: - https://jacobian.org/

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-man… - Respect everyone and mentor juniors who look up to you. - Don't accept leadership positions if you can't actively play office politics.

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/

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/

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/

> 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…