I'm the total opposite, my documentation is very thorough, my code looks like it was made by a monkey
this post was submitted on 31 May 2024
524 points (99.1% liked)
linuxmemes
26313 readers
101 users here now
Hint: :q!
Sister communities:
Community rules (click to expand)
1. Follow the site-wide rules
- Instance-wide TOS: https://legal.lemmy.world/tos/
- Lemmy code of conduct: https://join-lemmy.org/docs/code_of_conduct.html
2. Be civil
- Understand the difference between a joke and an insult.
- Do not harrass or attack users for any reason. This includes using blanket terms, like "every user of thing".
- Don't get baited into back-and-forth insults. We are not animals.
- Leave remarks of "peasantry" to the PCMR community. If you dislike an OS/service/application, attack the thing you dislike, not the individuals who use it. Some people may not have a choice.
- Bigotry will not be tolerated.
3. Post Linux-related content
- Including Unix and BSD.
- Non-Linux content is acceptable as long as it makes a reference to Linux. For example, the poorly made mockery of
sudoin Windows. - No porn, no politics, no trolling or ragebaiting.
4. No recent reposts
- Everybody uses Arch btw, can't quit Vim, <loves/tolerates/hates> systemd, and wants to interject for a moment. You can stop now.
5. π¬π§ Language/ΡΠ·ΡΠΊ/Sprache
- This is primarily an English-speaking community. π¬π§π¦πΊπΊπΈ
- Comments written in other languages are allowed.
- The substance of a post should be comprehensible for people who only speak English.
- Titles and post bodies written in other languages will be allowed, but only as long as the above rule is observed.
6. (NEW!) Regarding public figures
We all have our opinions, and certain public figures can be divisive. Keep in mind that this is a community for memes and light-hearted fun, not for airing grievances or leveling accusations. - Keep discussions polite and free of disparagement.
- We are never in possession of all of the facts. Defamatory comments will not be tolerated.
- Discussions that get too heated will be locked and offending comments removed. Β
Please report posts and comments that break these rules!
Important: never execute code or follow advice that you don't understand or can't verify, especially here. The word of the day is credibility. This is a meme community -- even the most helpful comments might just be shitposts that can damage your system. Be aware, be smart, don't remove France.
founded 2 years ago
MODERATORS
Like my professor used to say: "Implementation is trivial, a trained ape can do it."
The trained ape is AI and it works really well.
Hold on i gotta glue my pizza and drink my piss every 24hours before i finish this comment.
(Im joking)
I prefer concise and accurate documentation than clean code tbh. The reason is that if the documentation stated that it should perform something with side effects a,b,c then I at least know what to expect. When contributing, this also makes it easier to implement something because we have the requirement at hand. Understanding shitty code is easier than understanding human requirements. Shitty code is the language we use to talk with a computer, so at least you'll know exactly what will happen.
I think the same, I often find that people overestimate their ability to write self documenting code and with the added mess of automatic formatters it often becomes hard to read and understand. In my department I am one of the few who actually writes comments and readmes that explains the reason behind some decisions. I am very junior, less than a year of experience, so maybe I will be able to better understand code that other people write in the future. But for the time being I write my documentation and my comments in a way that someone who doesn't know anything about the project can understand, because I hate having to call coworkers because I can't figure out how the project handles x and y (bear in mind that is also caused by Java "best practices" with 45 abstraction layers)
He's doing a good job :3
My best READMEs are the ones I write well before I've finished the code. The README bears little resemblance to reality, but it's the easiest to read.
Am I the only one who writes the Readme as I add features and do my commits.
Don't leave your homework until the end and cram away just before it's due.
Code every other day.
Code. Then review and document.
I also try to maintain my feature list in my Readme. Essentially my roadmap. Work my way down the list and write Code as features are added/updated.
As long as you provide a list of dependencies, you're cool in my book
Code is more or less deterministic, communicating with other humans using something like the English language - much harder.
Lots of communication is open ended and up to interpretation especially with things like incorrect grammar usage and/or slang
Take your time, get it as close to right as you can the first go around
Them: "Read the docs, this is a mature project!"
The documentation: "Coming soon!"
Me: "It says its coming soon."
Them: "Its open source, how about you contribute instead of demand?"
Me: "What?"
System notification: "Banned, lol"
This is eerie close to home! Completely illogical answers, yet somehow I'm to blame π€¨...
I'm the opposite. Wanna join forces?
Definitely!
As long as your documentation doesn't require anything graphical, then I'm your man.
Nope, nonetheleast. Maybe a screenshot or two.
I'll send you a DM π.
This is like when I was in school and spend half of the time using "word art" to set fancy titles
I'm the opposite. I will write literally a book of poetry for the tiniest feature to justify my pay raise at the end of the year.
I think a lot of people are kind of bad at written communication. It's not an easy skill.
Often at work folks will write twice as many words and clauses as needed. The Hemingway editor ( https://hemingwayapp.com/ ) isn't perfect, but I recommend they take a look at it.
That hit me right in the gut.
This is why my programs don't come with documentation. If you want to use them, the best I can do is a messy script that "works for me".
Well, I for one am thankful you lot see so bad at explaining yourselves or I'd be out of a job
Love, the technical writer
I pride myself on writing pretty good technical docs. But there's always a motivation hurdle at the beginning, that I have to get over.
I do both well but it never ends. π