Does anyone have any good sources or suggestions on how I could look to try and begin to improve documentation within my team?

Documentation in software projecte, more often than not, is a huge waste of time and resources.

If you expect your docs to go too much into detail, they will quickly become obsolete and dissociated from the actual project. You will need to waste a lot of work keeping them in sync with the project, with little to no benefit at all.

If you expect your docs to stick with high-level descriptions and overviews, they quickly lose relevance and become useless after you onboard to a project.

If you expect your docs to document usecases, you’re doing it wrong. That’s the job of automated test suites.

The hard truth is that the only people who think they benefit from documentation are junior devs just starting out their career. Their need for docs is a proxy for the challenges they face reading the source code and understanding how the technology is being used and how things work and are expected to work. Once they go through onboarding, documentation quickly vanishes from their concerns.

Nowadays software is self-documenting with combination of three tools: the software projects themselves, version control systems, and ticketing systems. A PR shows you what code changes were involved in implementing a feature/fixing a bug, the commit logs touching some component tells you how that component can and does change, and ticketing shows you the motivation and the context for some changes. Automated test suites track the conditions the software must meet and which the development team feels must be ensured in order for the software to work. The higher you are in the testing pyramid, the closer you are to document usecases.

If you care about improving your team’s ability to document their work, you focus on ticketing, commit etiquette, automated tests, and writing clean code.

That way we’ll just find maintainers went near extinct over time, just like COBOL developers that are as rare as they are expensive.

Care to take a shot at figuring out why COBOL is still used today?

I mean, feel free to waste your time arguing for rewrites in your flavor of the month. That’s how many failed projects start, too, so you can have your shot at proving them wrong.

But in the meantime you can try to think about the problem, because “rewrite it in Rust” is only reasonable for the types who are completely oblivious to the realities of professional software development.

You’d have had me ignore them all and keep using C for everything.

Please tell me which language other than C is widely adopted to develop firmware.

You’re talking about so many up-and-comers during all these decades. Name one language other than C that ever came close to become a standard in firmware and embedded development.

Right.

Yeah, because the new tools are never actually better, right?

Well, yes. How many fads have come and went? How many next best things already died off? How many times have we seen the next best thing being replaced by the next best thing?

And yet, most of the world still runs on the same five languages: C, Java, C++, C#, JavaScript.

How do you explain that, with so many new tools being so much better than everything?

Might it be because fanboys tend to inflate their own definition of “actually better”, while turning a blind eye to all the tradeoffs they need to pretend aren’t there?

If you had a grasp on the subject you’d understand that it takes more than mindlessly chanting “tools” to actually get tangible improvements, and even I’m that scenario often they come with critical tradeoff.

It takes more than peer pressure to make a case for a tool.

That seems like a poor attitude imo.

Why do you believe that forcing something onto everyone around you is justifiable? I mean, if what you’re pushing is half as good as what you’re claiming it to be, wouldn’t you be seeing people lining up to jump on the bandwagon?

It’s strange how people push tools not based on technical merits and technological traits, but on fads and peer pressure.

Clearly Rust is a conspiracy.

Anyone in software development who was not born yesterday is already well aware of the whole FOMO cycle:

1. hey there’s a shiny new tool,
2. it’s so fantastic only morons don’t use it,
3. oh god what a huge mistake I did,
4. hey, there’s a shiny new tool,

They’re a member, because they find Rust useful. This is just them saying another time that they find Rust useful.

Fans of a programming language stating they like the programming language is hardly thought-provoking stuff. There are also apps written in brainfuck and that means nothing as well.

The whole idea to check the donations came from stumbling upon this post which discussed costs per user.

Things should be put into perspective. The cost per user is actually the fixed monthly cost of operating an instance divided by the average number of active users.

In the discussion you linked to, there’s a post on how Lemmy.ml costs $80/month + domain name to serve ~2.4k users. If we went through opex/users metric, needlessly expensive setups with low participation would be a justification to ask for more donations.

Regardless, this is a good reminder that anyone can self-host their own Lemmy instance. Some Lemmy self-host posts go as far as to claim a Lemmy instance can be run on a $5/month virtual private server from the likes of scaleway.

Is there something else I’m not seeing?

Possibly payment processing fees. Some banks/payment institutions charge you for a payment.

I think you’re trying too hard to confuse yourself.

With what in mind? Evading NULL?

Depends on your perspective. It’s convenient to lean on type checking to avoid a whole class of bugs. You can see this either as avoiding NULL or use your type system to flag misuses.

Languages that make use of references rather than pointers don’t have this Dualism. C# has nullable references and nullability analysis, and null as a keyword.

C#'s null keyword matches the monadic approach I mentioned earlier. Nullable types work as a Maybe monad. It’s the same concept shoehorned differently due to the different paths taken by these languages.

I’ve never heard of evading null with a Null object.

This is quite standard, and in fact it’s even a safety feature. C++ introduced nullptr defined as an instance of std::nullptr_t explicitly with this in mind.

https://en.cppreference.com/w/cpp/language/nullptr

This approach is also quite basic in monadic types.

It doesn’t matter, why the present is garbage, it’s garbage and we should address that. Statements like this are the engineering equivalent of “it is what it is shrug emoji”.

I don’t think your opinion is grounded on reality. The “it is what it is” actually reflects the facts that there is no way to fix the issue in backwards-compatible ways, and it’s unrealistic to believe that vulnerable frameworks/websites/webservices can be updated in a moment’s notice, or even at all. This fact is mentioned in the article. Those which can be updated already moved onto a proper authentication scheme. Those who didn’t have to continue to work after users upgrade their browser.

Can you clarify how “Not even Github managed to pull that off”?

GitHub actions has an atrocious user experience, to the point that even a year or so ago people where doubting it was production-ready.

Sure, you can put together a pipeline. But I challenge anyone to try it out with GitHub actions and then just try to do the same with GitLab or even CircleCI or Travis.

The fact that people compare GitHub Actions go Jenkins of all things is everything anyone needs to know about it’s user experience.

There would be no other incentive for companies to buy it.

A company might want to extend it’s service offering with a build pipeline/CICD system, and buying GitLab would get them the best-in-class service.

Microsoft bought GitHub for much of the same reasons, and GitHub didn’t went to hell after the acquisition.

I don’t think it makes any sense to mention source hut because none of the features you mentioned are killer features (or relevant. Why should I care about implementation details of feature tracking?) and it completely fails to address GitLab’s main value proposition: it’s CICD system.

Anyone can put up any ticketing system. They are a dime a dozen. Some version control systems even ship with their own. CICD is a whole different ballgame. It’s very hard to put together a CICD system that’s easy to manage and has a great developer experience. Not even GitHub managed to pull that off. GitLab is perhaps the only one who pulled this off. A yams file with a dozen or so lines is all it takes to get a pipeline that builds, tests, and delivers packages, and it’s easy to read and understand what happens. On top of that, it’s trivial to add your own task runners hosted anywhere in the world, in any way you’d like. GitLab basically solved this problem. That’s why people use it.

There’s also alternatives with custom ci jobs within non GitHub/lab within the git universe that may help out with those sorts of operations.

Why would anyone subject themselves to explore nonstandard and improvised solutions to try to fit a usecase that fails to meet your needs to a tool that was not designed to support it?

Do people enjoy creating their own problems just to complain about them?

I don’t think they did an exceptional job keeping teams separated. In fact, I think monorepos only end up artificially tying teams down with an arbitrary and completely unnecessary constraint.

Also, not all work is services.

You just referenced two languages that don’t have proper sum types. lol.

You’re complained about “Proper HTTP implementations in proper languages”.

I provided two concrete examples of two of the most popular and production-grade programming language ever developed.

I can provide more.

You then tried to weasel out by moving your goal post from “Proper HTTP implementations in proper languages” to “languages that don’t have proper sum types”.

I won’t waste more of my time with you. Whatever you’re posting lacks relevance and does not justify any attention from anyone.