The Contribution Manual

Talk to the maintainer first, you dumb faggot.

No, nobody is mandated, but it would be nice if more people cooperated. Just because you don't have to doesn't mean you shouldn't, just like just because you don't have to write unit tests doesn't mean you shouldn't.

Serious proprietary software does have those documents, and not so serious proprietary software with smaller teams has a guy personally explaining to you how shit works for a week before you are expected to contribute on your own.

You are missing the point. Yes, what we have satisfies the bare minimums, but we can go beyond and we can do better.

all you need to do is code better, the purpose of all these projects

t. nogrammer

It might be, and this is just a suggesstion here, but maybe your average coder thinks that in-depth documentation should be up to others, and not them.

Not him, but my grammar comprehension sucks, I think.

suck my white cis benis you absolute unit

I think a lot of programmers are too intelligent for their own good. They can write a several thousand line of code source file with no comments and they will know where everything is. I'm a brainlet, which is why I always try to split things up and have docstrings even for functions which are not part of a module's public interface.

Is this how a brainlet adds a new feature?
You should just use tools to automate finding the place where you need to add the new feature. Look at something similar to what you are adding and then copy that as a basis for your addition.
There is no need to understand every line of code.

Is this how a brainlet finds the cure to cancer?
You should just use tools to automate finding the place where you need to investigate the cure. Look at a similar disease to what you are investigating and then copy the drug used to treat it as a basis for your cure.
There is no need to understand every type of cancer ever.

Reposting because I think my previous one got eaten.

Good lord finally a decent post on Zig Forums (only took linux getting fucking comped) and all these dipshit 12-year-old no-coders are out in force...

I struggle with the same problems . I've wanted to help contribute to code-bases but the vast majority, let alone having any form of documentation/rhyme or reason to file organization, often don't even HAVE a visible main file. There are even cases where a library I wanted to use was so poorly documented that I wound up having to reimplement it myself from scratch just from the theory of it because it would take even longer to learn their particular brand of autism, or completely kludge up my own code.

Anyone that tells you that you are wrong here is either autistic, trolling, or has never had a project that grew to more than 5 files of code. We don't really need to make writing documentation easier, rather what needs to be done is to spread awareness of existing tools which can already do this such as pandoc, doxygen, and methods of using code-gen techniques and sed to generate docs. The trick here is that we need to work on providing more resources on when it is time to get dirty and actually WRITE the documentation; HOW to write it; What things to cover, etc...

For example, what precisely constitutes a good HACKING.txt file? What elements should it contain? Why? In my case, I tend to to keep code-level documentation (why did I do X, for example) as comments in my code, with theory-level documentation (how does something actually work) in a separate file, but I can't help feeling as though it is lacking, even despite me using (admittedly intelligent) no-coders as test-readers for clarity. Admittedly, I am a solo-dev, so maintaining clarity in docs for me is not as difficult as I imagine it would be for a team.

For my own thoughts here - I personally think a HACKING.txt file should be more like an introductory info dump. It would serve as essentially a table of contents with a bit of extra high-level info in it that links(or something like "for more info, view doc/blah/clockwork_stupidity.txt") to the more verbose technical write-ups if necessary. The key here is to write even your technical info in common english. There's no need to masturbate with a dictionary if plain, simple english will suffice to convey an idea. Will this allow retards to understand your code? Yeah, it will, but that is kind of the point of documentation last time I checked - to free yourself from answering questions and be able to focus on writing more code.

This leads us to the problem: most modern devs are retarded lazy fucks. They won't write documentation beyond a shitty raw doxygen dump. They will act like "read the source" is even a remotely viable stance on documentation when their code grows beyond 2-3 files or is written in nothing but hacky header retardation and C++ template stupidity or is full-on pajeet code. They will even tell you to use an IDE as they demonstrate they are no better than the average pajeet (sometimes even terrifyingly worse - I've actually bumped into competant pajeets).

..Except when there's that one tiny fucking thing that depends on what you are tweaking and causes either unintended breakage for another feature (yes, lots of things are written this poorly) or even can cause a massive security risk. Congrats on writing pajeet code if you do this.

Completely agreed. They don't understand that the true measure of intellect is not in how many words one can string together, but how well one can convey their thoughts with less.