The Slow Collapse of MkDocs
82 points by mitsuhiko
82 points by mitsuhiko
So… sharing the source isn’t the problem here. The issue is the GitHub working environment. I’m not interested in the smokey boys-only-club atmosphere, it feels starkly unprofessional.
We’re not having any more conversation in all-male online spaces. Not happening.
[httpx github discussion] I don't want to continue allowing an online environment with such an absurdly skewed gender representation. I find it intensely unwelcoming, and it's not reflective of the type of working environments I value.
Maybe I'm missing some context, or some manifesto but um, does lovelydinosaur think women (hi!) aren't on Github?
I don't have the energy to find a good source for it (can someone help out here?), but I'd assume someone concerned about skewed gender representation would know that it's like this across the entirety of tech, not just Github, right?
I see that dino's org is encode, which seems to still host all repos on Github, instead of moving to a platform that has a better gender representation (which one does? can you send me an invite? :P).
I don't think it is actually worth thinking too much about it as I get the feeling we are rather watching the breakdown of someone trying to grasp for straws. Sometimes it is hard to accept that your favorite project has outgrown your time, mental capacity or interests. Especially when you are also trying to make other big FOSS projects happen and have a life outside of that.
It is of course way easier to silence the judging voices by simply blaming your community for their body or assuming their sexuality.
I dunno, I think that needs a non-charitable reading.
If I was sick of leading a project, especially once that gives this much pushback to my changes, I'd hand over the keys / throw the white flag. Dino clearly cares about the project, even if it's misguided based on the sentiment, else they could have just stayed out of mkdocs after their departure.
Mind you, I don't really know if Dino had a bad experience in a mostly male space, and frankly it's also none of our business, but it could explain why there's so much of a focus on gender here.
for their body or assuming their sexuality.
(i don't think hardware or sexuality is relevant here, the mention is explicitly gender)
If I was sick of leading a project, especially once that gives this much pushback to my changes, I'd hand over the keys / throw the white flag.
I have done this repeatedly and it's never easy.
I'd hand over the keys / throw the white flag
Which is the sane reaction, but that's you. Some people simply associate way too much with their projects. And if they walked away like years ago and then come back there was clearly not enough mental distancing.
The fact the community had to argue against the no-plugins approach twice should already show how far away they are from reality.
(s/body/gender/g)
Yeah I'm not sure what is up but I wrote about drama involving lovelydinosaur unceremoniously disabling (and effectively removing) issues and discussions on DRF a year ago. They're clearly overburdened at the moment.
The context I had assumed was "…they are working on MkDocs v2 in private." My thought was that the selected contributors to the private repository did not have the same skewed gender representation than the general population of GitHub.
In other words, a distinction was being made between GitHub¹, the series of Microsoft servers where a bunch of bytes are stored, and GitHub², a community of developers who comment on public repos on GitHub¹. I could understand someone keeping a repo private to access the resources provided by GitHub¹ while avoiding GitHub² (or engaging with only a chosen subset).
Software projects that do a ground-up rewrite should really just rebrand. It's less confusing for everyone. Wanting to keep the brand while rewriting everything from scratch? That starts to feel like false advertising toward the open source community.
There's plenty of counterexamples though. Major versions without rebrands but with breaking changes get released all the time (particularly in JS-land), and sometimes rewrites happen without the user noticing (see: fish shell). I think those sentiments are always a reflection of how much you trust the maintainer to get the balance right, and I guess in this case the expectations are low.
(see: fish shell)
If you rewrite a piece of software I use without me noticing, I want to high five you. :)
yeah, fish is a good counterexample. I think the key point here is a ground up rewrite and backwards incompatibility at the same time; I think the fish team was careful to make the rewrite compatible.
anyway, I think if properdocs really is a drop-in replacement it will likely end up as the migration strategy if choice if/when pip install mkdocs ends up pulling in v2 and silently breaking people's systems.
Ahhh... People fighting for a little bit of status and power over an open source project. The classic old school online obnouxiousness.
Reading half of this was unbearably cringe. How old are these people? Do they know they can clone the project and do whatever they want in terms of development? But no. They want to have their name one the project with GitHub a stars. Grown people fighting over Monopoly money.
wow, I had no idea all of this was happening behind the scenes. im glad i stayed away from this project.
i considered mkdocs for https://docs.tangled.org/ but ultimately hacked together a pandoc script in about 30 minutes: https://blog.tangled.org/docs.
for anybody looking to make a docsite, i can recommend rolling your own docs with pandoc, TigerStyle.
It was an interesting read, a cautionary tale about governance. I use httpx quite a lot (written/maintained by one of the protagonists of the blog post) and realized there are no issues on the project anymore, with this justification. I hope everyone will find their peace long-term, hopefully this means development will continue.
Jeez, it feels like half the open source projects I love most eventually collapse due to maintainer drama.
Whoa! Thanks for the hint, I guess I will be not migrating to httpx from requests then… (like a lot of projects already did)
Huh, I stopped using requests because $REASONS, and started using httpx sometimes. What should I use!?
(For work I'm mostly using urllib.request raw, because for what I'm doing it's hugely convenient to have no dependencies. But that's a bit annoying sometimes.)
The standard answer used to be urllib3 and I think that is still generally correct.
I reach for aiohttp generally. I've been a python dev for over 10 years and have never seen anyone use urllib3 directly.
This is a testament to the breadth of the Python community: I've been a Python dev for over 10 years as well, and I only used aiohttp for the first time recently. Before that I always reached for urllib3 or requests (which just wraps the former).
I remember there being some concern around the stability of the original developer of Requests, but my reading of things is that it is now being maintained by a more level-headed crew. So it's fine to use from that pov, but I'm not sure if it's as "modern" as httpx or others.
There goes my strategy of moving our internal docs out of Confluence and into mkdocs.
Oh wait, no, it’s still better than confluence 🤣
opinions (or drama) aside, this post is well written documented with timeline scrolls and the gist of longer discussions. kudos to the author. nice read indeed.
Zensical is really good and was able to migrate a large mkdocs repo in less than 30 minutes. Kudos to that team for their work on that.
No idea why at the first sign of trouble contributors didn't just immediately fork it and go on with their lives. Seems like the original maintainers initiallly had no desire for changes (until the redesign).