4 ms·
This is /extremely/ uncharitable. It depends more on the project. For example, both Go and .NET are very well written engineering achievements with thorough do
by fny 4y ago
This is /extremely/ uncharitable. It depends more on the project.
For example, both Go and .NET are very well written engineering achievements with thorough documentation. Many, many other deeply influential projects have also been absorbed by the Apache Foundation or other FOSS initiatives.
Furthermore, every software megacorp has boat loads of teams working on hundreds even thousands (!) of different open source projects. The quality naturally varies.
Let me pick two more esoteric projects as a point of comparison.
Yandex Odyssey [0] an advanced multi-threaded PostgreSQL connection pooler and request router. Figuring out how exactly and when to use this is not quite clear. There is no "getting started" guide for this package. There is barely any explanation for how it works or what it does.
pg_auto_failover [1] run by Citus (owned by Microsoft) monitors and manages automated failover for a Postgres cluster. This repo even has diagrams explaining the workflow and complete instructions.
Frankly, it's unreal just how much code is open nowadays especially from the giants.
Visual Studio, for example, had been under lockdown for 20 years. Now Visual Studio Code is being developed in the open and has extremely thorough documentation that walks developers through the entire build process in painstaking detail.[2] This is a blazing fast editor written in JavaScript of all things! Or consider TypeScript, an incredible engineering feat. There is an entire repo dedicated to engineering notes on how the compiler works with links to interesting feature contributions and a video! [3]
I'm only picking Microsoft here as the primary example since you dumped on them the hardest.
*No other industry does this. It is absolutely wild how much copyleft influenced software culture.*
[0]: https://github.com/yandex/odyssey https://github.com/yandex/odyssey
[1]: https://github.com/citusdata/pg_auto_failover https://github.com/citusdata/pg_auto_failover
[2]: https://github.com/microsoft/vscode/wiki/How-to-Contribute https://github.com/microsoft/vscode/wiki/How-to-Contribute
[3]: https://github.com/microsoft/TypeScript-Compiler-Notes/ https://github.com/microsoft/TypeScript-Compiler-Notes/
- markus_zhang 4y agoI guess the more new and business facing (cloud and clickops), the worse?
- petre 4y ago> There is no "getting started" guide for this package. There is barely any explanation for how it works or what it doees. Welcome to Russian software or hardware. Nginx is an exception with okayish documentation.
- weakfish 4y agoIs there a reason or point for calling out Russia?
- eurasiantiger 4y agoThe global situation, for starters.
- weakfish 4y ago… is unrelated to software as far as I am aware
- eurasiantiger 4y agoWell, let’s increase your awareness, then. https://en.wikipedia.org/wiki/Cyberwarfare_by_Russia https://en.wikipedia.org/wiki/Cyberwarfare_by_Russia
- weakfish 4y agoOkay, you’re just being obtuse. The original comment was about the quality of Russian software documentation. That is unrelated to cyberwarfare, a subject I wrote about extensively, and earned recognition for. [0] [0] https://spia.news.chass.ncsu.edu/2022/05/13/john-allison-receives-2022-erika-fairchild-outstanding-paper-award/ https://spia.news.chass.ncsu.edu/2022/05/13/john-allison-rec...
- eurasiantiger 4y agoYou are assuming two things: 1) everyone knows you and what you have written and that makes you the authority (not true, obviously, and kind of makes you look like a top hat) 2) what you have written applies to the situation (not true; Russia is an authoritarian dictatorship where every business entity is potentially a state actor)
- x4m 4y agoI concur that Odyssey docs are insufficient to build a big picture. But I'm trying to answer every question in the Internets about Odyssey :) Documenting is hard - everything seems obvious to me, but understand that may things are not that obvious. // Odyssey maintainer