Join devRant
Do all the things like
++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatar
Sign Up
Get a devDuck
Rubber duck debugging has never been so cute! Get your favorite coding language devDuck
Buy Now
-
Every fkn 3 to 4 days, some random dev shows up in my office really really fkn confused and frustrated about something he doesn't understand - because I have a dark secret.
Sometime, in cold lonely nights, when no one is watching, I write my documentation before the actual code.
Somehow, sometimes documentation without code attached to it makes it to production.
Today someone yelled at me for wasting his time because he wasted 3 hours trying to find the code the documentation belongs to - and demented I stop the practice from now on.
Agh.13 -
Once Ashish was travelling by train in A/c class. He was traveling from Mumbai to Bangalore!
He was traveling alone!
Some time later, a Beautiful lady came and sat in the opposite berth!
Ashish was pleasantly Happy!
The lady kept smiling at him! This made Ashish even more Happy!
Then she went and sat next to him!
Ashish was bubbling with Joy!
She then leant towards him and whispered in his ear " Hand over all your valuables, cash, cards, mobile phone to me
else I will shout and tell everybody that you are harassing and misbehaving with me"
Ashish stared blankly at her!
He took out a paper and a pen from his bag and wrote " I can not hear or speak. You write on this paper whatever you want to say"
The lady wrote everything what she said earlier and gave it to him!
Ashish took her note, kept it in his pocket!
He got up and told her in clear tones..."Now shout & scream!!"
MORAL OF THE STORY : *DOCUMENTATION IS VERY IMPORTANT*
😄😀😄4 -
Documentation is like sex.
When it's good, it's very good.
When it's bad, it's better than nothing.25 -
To write 1000 lines of JS, I need 1 cup of coffee.
To write 100 lines of documentation I need 100 cups of coffee.
For some reason time stops when I open confluence9 -
I find it super annoying, this trend where no one wants to write learning documentation anymore, but instead put up a bunch of demo videos and video "training courses."
I don't want to spend 5 minutes watching you do something that would take me 10 seconds to read. I can't search for terms in your video, and I can't use them as a general reference manual. I can't go at my own pace, easily keep my place between devices, enter code as you go, the list of cons goes on and on.
I would rather pay you money for a good eBook (and no, PDFs don't count), than to have the only realistic way to learn about your software be a playlist on your YouTube channel.
This, however, this...
Went to check out Ansible again, because I've heard good things lately and it's been a couple years since I've looked at it.
Took me a while to find their docs because there's almost no mention of anything on the home page except trying Tower for free.
Found the docs. The first item there is the Quick Start Video and I think, "Cool. That's a good use of video, showing off the product."
I dig out some headphones, click play:
"Ansible is a powerful" BOOM!
Enter my email to watch the video?!
Ah, forget it. Maybe I'll see you next time, Ansible.
9 -
First rant here. Long, but please bear with me:
So after slogging my ass off in various early stage startups for over 4 years and keeping up with the almost non-existent development process, I joined an organisation which has some of the brightest and smartest minds I have had the pleasure to work with.
Mind you, this company is the market leader in it's field and has a 50+ people in it's tech team and the quality of work is pretty impressive.
Now for this week's sprint, I was asked to develop a feature which already exists on the Android app and they want to introduce in the iOS app too. The backend APIs are all in place and all I need to do is build it with virtually no dependency. My PM asks me to start with the UI and ask the backend dev for the API list whenever I need them.This is where the story turns.
For my first API, I go to the backend dev and ask him to share the API documentation and he looks at me as if I have asked him to dance the fucking cha cha. With a straight face he tells me that, 'The organisation doesn't maintain any kind of documentation for it's APIs.' Now this really shocks me. Even in a 5 men tech teams I have worked on, we have always maintained a spec doc for the APIs and this is a company which is known for it's tech practices.
Being the new guy I compose myself and ask if they have anything for me here: Postman collection, a workflowy doc, a goddamn txt file; anything which might help me, and he laughs at my dilusion and says no.
Dejected, I ask for a way to get the APIs and I am told that there are only two ways: either I keep bothering the Android dev for the APIs(No, I don't have the access to the android repo and nor am I gonna get it) which he had worked on 4 months back or I install the prod app on my phone, and use Charles to get every fucking API which is really, really annoying.
I thought writing out this rant would make me feel better, turns out it just made me angrier. Why the fuck can't they document such an important thing!?12 -
Every step of this project has added another six hurdles. I thought it would be easy, and estimated it at two days to give myself a day off. But instead it's ridiculous. I'm also feeling burned out, depressed (work stress, etc.), and exhausted since I'm taking care of a 3 week old. It has not been fun. :<
I've been trying to get the Google Sheets API working (in Ruby). It's for a shared sales/tracking spreadsheet between two companies.
The documentation for it is almost entirely for Python and Java. The Ruby "quickstart" sample code works, but it's only for 3-legged auth (meaning user auth), but I need it for 2-legged auth (server auth with non-expiring credentials). Took awhile to figure out that variant even existed.
After a bit of digging, I discovered I needed to create a service account. This isn't the most straightforward thing, and setting it up honestly reminds me of setting up AWS, just with less risk of suddenly and surprisingly becoming a broke hobo by selecting confusing option #27 instead of #88.
I set up a new google project, tied it to my company's account (I think?), and then set up a service account for it, with probably the right permissions.
After downloading its creds, figuring out how to actually use them took another few hours. Did I mention there's no Ruby documentation for this? There's plenty of Python and Java example code, but since they use very different implementations, it's almost pointless to read them. At best they give me a vague idea of what my next step might be.
I ended up reading through the code of google's auth gem instead because I couldn't find anything useful online. Maybe it's actually there and the past several days have been one of those weeks where nothing ever works? idk :/
But anyway. I read through their code, and while it's actually not awful, it has some odd organization and a few very peculiar param names. Figuring out what data to pass, and how said data gets used requires some file-hopping. e.g. `json_data_io` wants a file handle, not the data itself. This is going to cause me headaches later since the data will be in the database, not the filesystem. I guess I can write a monkeypatch? or fork their gem? :/
But I digress. I finally manged to set everything up, fix the bugs with my code, and I'm ready to see what `service.create_spreadsheet()` returns. (now that it has positively valid and correctly-implemented authentication! Finally! Woo!)
I open the console... set up the auth... and give it a try.
... six seconds pass ...
... another two seconds pass ...
... annnd I get a lovely "unauthorized" response.
asjdlkagjdsk.
> Pic related.
25 -
tl;dr I need ideas on how to warn the next dev(s) that the company is a dumpster fire.
------
For the past week (actual time: three days) I've been writing documentation for work, since there isn't any. It's been okay, I guess. Certainly more interesting than anything else I've done at work in months.
I'm up to 10k words / 67kb of markdown, and I think I'm done. I could easily write another 30k words on everything, but I just can't care enough.
However, what I do care about is warning the next dev(s) about how terrible the place is to work, so I want to add little references or hints or other such things to my writing. To complicate that, there's a contractor dev who said he will edit the document to strip out my commentary and make it "friendly" for the next person. (I can kind of see why: I've been quite honest about the situation of everything, and it's pretty dire. If they read it as-is, they might just walk out the door. I certainly would have.) I'm also going to commit it to the repo, and afaik he doesn't have push rights, so he can't force-push and remove it. (and a force-push by someone else, adding my documentation immediately after I leave... that would be pretty fishy, too.)
Anyway, at someone's suggestion, I added a "three envelopes" reference in the access phrase generator section. I also wrote "Promises made outside of ES6 will not resolve" -- in the warning section of a document almost entirely about Rails. (because the boss has broken every single promise he has ever made me.)
What other hints and subtle warnings could I add?
(And hurry: tomorrow is my last day! ;3)23 -
“Our code is our documentation - it’s produced in such a way as to be explanatory, logical and clear, and annotated if/where needed”
Really?? That's the reply you give me when I asking API documentation for handover ?5 -
it's funny, how doing something for ages but technically kinda the wrong way, makes you hate that thing with a fucking passion.
In my case I am talking about documentation.
At my study, it was required to write documentation for every project, which is actually quite logical. But, although I am find with some documentation/project and architecture design, they went to the fucking limit with this shit.
Just an example of what we had to write every time again (YES FOR EVERY MOTHERFUCKING PROJECT) and how many pages it would approximately cost (of custom content, yes we all had templates):
Phase 1 - Application design (before doing any programming at all):
- PvA (general plan for how to do the project, from who was participating to the way of reporting to your clients and so on - pages: 7-10.
- Functional design, well, the application design in an understandeable way. We were also required to design interfaces. (Yes, I am a backender, can only grasp the basics of GIMP and don't care about doing frontend) - pages: 20-30.
- Technical design (including DB scheme, class diagrams and so fucking on), it explains it mostly I think so - pages: 20-40.
Phase 2 - 'Writing' the application
- Well, writing the application of course.
- Test Plan (so yeah no actual fucking cases yet, just how you fucking plan to test it, what tools you need and so on. Needed? Yes. but not as redicilous as this) - pages: 7-10.
- Test cases: as many functions (read, every button click etc is a 'function') as you have - pages: one excel sheet, usually at least about 20 test cases.
Phase 3 - Application Implementation
- Implementation plan, describes what resources will be needed and so on (yes, I actually had to write down 'keyboard' a few times, like what the actual motherfucking fuck) - pages: 7-10.
- Acceptation test plan, (the plan and the actual tests so two files of which one is an excel/libreoffice calc file) - pages: 7-10.
- Implementation evalutation, well, an evaluation. Usually about 7-10 FUCKING pages long as well (!?!?!?!)
Phase 4 - Maintaining/managing of the application
- Management/maintainence document - well, every FUCKING rule. Usually 10-20 pages.
- SLA (Service Level Agreement) - 20-30 pages.
- Content Management Plan - explains itself, same as above so 20-30 pages (yes, what the fuck).
- Archiving Document, aka, how are you going to archive shit. - pages: 10-15.
I am still can't grasp why they were surprised that students lost all motivation after realizing they'd have to spend about 1-2 weeks BEFORE being allowed to write a single line of code!
Calculation (which takes the worst case scenario aka the most pages possible mostly) comes to about 230 pages. Keep in mind that some pages will be screenshots etc as well but a lot are full-text.
Yes, I understand that documentation is needed but in the way we had to do it, sorry but that's just not how you motivate students to work for their study!
Hell, students who wrote the entire project in one night which worked perfectly with even easter eggs and so on sometimes even got bad grades BECAUSE THEIR DOCUMENTATION WASN'T GOOD ENOUGH.
For comparison, at my last internship I had to write documentation for the REST API I was writing. Three pages, providing enough for the person who had to, to work with it! YES THREE PAGES FOR THE WHOLE MOTHERFUCKING PROJECT.
This is why I FUCKING HATE the word 'documentation'.36 -
Worked 8 hours on a feature to send attachments from our system (A) to another (B) via B's API. Perfect code, yet I couldn't make it work. B's API has full and extensive documentation for said feature. Contacted B to ask about it, got reply: "Oh yeah - we havent enabled that yet but thought it was handy to have it ready in the docs"
FML
4 -
Jesus Christ. Dagger2's documentation has got to be the most convoluted shit I have ever laid my eyes on.
The sheer mental gymnastics I had to do to get through this one line at 2:30 am...
13 -
Once IT Engineer was travelling by train in A/c class.
He was traveling alone!
Some time later, a Beautiful lady came and sat in the opposite berth!
IT Engineer was pleasantly Happy!
The lady kept smiling at him! This made IT Engineer even more Happy!
Then she went and sat next to him!
IT Engineer was bubbling with Joy!
She then leant towards him and whispered in his ear " Hand over all your valuables, cash, cards, mobile phone to me
else I will shout and tell everybody that you are harassing and misbehaving with me"
IT Engineer stared blankly at her!
He took out a paper and a pen from his bag and wrote " I can not hear or speak. You write on this paper whatever you want to say"
The lady wrote everything what she said earlier and gave it to him!
IT Engineer took her note, kept it in his pocket!
He got up and told her in clear tones..."Now shout & scream!!"
MORAL OF THE STORY : DOCUMENTATION IS VERY IMPORTANT
😄😀😄4 -
Job listing I just saw:
Our lead and only developer just retired after 15 years of maintaining the codebase. We need someone who is capable of working with large amounts of undocumented and untested code.
PS: This was a company that makes medical software.8 -
Documentation is like sex... When it's good, it's very good. When it's bad, it's better than nothing.4
-
Day 2 of writing documentation: still ready to go insane from repeating myself and am reconsidering everything I have ever done in my life...
8 -
FUCKING TELEGRAM FUCK YOU STAY IN YOUR FUCKING API DOCUMENTATION AND STOP FUCKING TESTING YOUR SHIT ON A PRODUCTION SYSTEM WHY WOULD YOU DO THAT FUCK OFF WHY AM I EVEN DEVELOPING SHIT FOR YOUR PLATFORM ANYMORE WHEN FOLLOWING YOUR DOCUMENTATION LEADS TO FUCKING ERRORS AND WE HAVE TO DECOMPILE AND REVERSE ENGINEER YOUR FUCKING "OPEN SOURCE" APPS BECAUSE YOU DONT EVEN BOTHER TO FUCKING UPDATE THE SOURCE CODE ONCE A YEAR WHAT THE FUCK
Thank you for your attention7 -
Now don't get me wrong, I love the multicultural aspect of open source coding.
But for the love of everything that that is sane, please do not write the basic readme and code in English, and then write the entire documentation for the code in another language.
(Yay first rant)
7 -
Uh, I gotta do Task #1337. It better is a good one!
*reads the title*
"Write technical documentation for... "
... D'oh! -
That moment when you search for Microsoft documentation and realize there is none, so you go search for source code and realize there isn't any of that either. 😑5
-
I am sure this has happened to all of us in some extent with some variations.
Colleague not writing comments on code.
Ask him something like "How am I suppose understand that piece of garbage you have written when there is no comments or documentation?"
This keeps happening for a long time. Some time after, I write a kernel module using idiomatic C and ASM blocks for optimizations (for some RTOS) and purposely not write neither documentation nor comments.
When he asked for an explanation, I answered to everything he questioned as general as I could for "that trivial piece of code".
After that he always documents his code!
Win! 🏆4 -
I finally got Redux-Form’s `initialValues` to work! Wooooo~!
/giphy confetti cheering
It turns out I haven’t actually been doing anything wrong for the past week. I mean, I've been working on other things during that week, too, but I've been trying to solve this the entire time.
The cause? ReduxForm made a breaking change awhile ago (v5; we’re using v7) that prevents the `initialValues` prop from working if you decorate your form component in the wrong order. Many examples online are incorrect because of this.
Basically, the decorators `reduxForm` and `connect` do not commute:
Incorrect:
`reduxForm(...)( connect(..., {...})(form) )`
vs Correct:
`connect(..., {...})( reduxForm(...)(form) )`
But what really pisses me off is that the fucking documentation specifically fucking states that you may decorate your component IN ANY [FUCKING] ORDER.
/giphy that is [fucking] false
So, I've been following example after [fucking] example that either list these in the wrong order, or I just don't notice the different order because it doesn't matter. AND because of that NONE OF THE [...] EXAMPLES WORK.
ARGH.
I've been pacing around the office trying to figure this out for days. I've rewritten my code three times to try to solve this. I've written two workarounds for it only to rip them out and try again because they both broke some other part of the UX. (e.g. causing false validation errors after rerender)
just. hafhsldkjhgjkhagklwhsdjfkahslf. 😡
/giphy angry hades
You know how I discovered this?
I found it in a github ticket. One solitary, untagged ticket from October of last year. Not a single goddamn post anywhere else mentioned this. And the [...] documentation specifically [...] states the [...] opposite!
Bloody [...] hell.
but it finally works.
as;kgjhaekl;gahgjkdflssdafh.
I could scream.6 -
People should fucking document their code. I have to implement something using someone's code. And I have no idea what I'm doing.6
-
I dunno if anyone else has said this here but
FUCK WORDPRESS DOT COM
FUCK WORDPRESS DOT ORG
FUCK WORDPRESS PLUGINS
FUCK THEIR DOCUMENTATION16 -
Ironically, the face I make when a project has no documentation is the same one I make when someone asks me to write documentation.
1 -
🤘 😈😈😹 🤘
Wordpress documentation...
"
Hi all, 😎 welcome to wordpress.
Use it as your last resort. Fuck all programming langs. Php is love, php is life."
Oh by the way documentation also says:
"
Wordpress gives you all the freedom you can imagine. Say for instance... You can use any language for server EXCEPT python, ruby, java, c# and many more.[note: Keep looking for the updated list of EXCEPT as new languages come we add it here.]
"
😂😂😂2 -
!rant
http://Devdocs.io
Somebody on here commented the link and I just had to make sure everyone knows about it.9 -
Just came back to an old project I haven't touched in a while and realized I did an awesome job documenting it. It's almost annoying my level of detail. I'm proud of my past self for thinking of me now.3
-
Rant::aboutMyself(my_code){
Wrote 500+ lines of code without proper documentation. Got 200 little bugs. Got frustrated. Gave up on code. Started documenting it. Step by step. Resolved many silly mistake while documenting the code. Completed documentation. Run the program . Bugs reduced to 10. I'm sooo happy. I LOVE DOCUMENTATION 😍
}2 -
This is one of my favorite lines of documentation 😁
Found in the description of flags for SVN commands: http://svnbook.red-bean.com/en/1.7/...
-
TLDR: crappy api + idiot ex client combo rant // devam si duška
I saw a lot of people bitching about APIs that don't return proper response codes and other stuff..
Well let me tell you a story. I used to work on a project where we had to do something like booking, but better..crossbreed with the Off&Away bidding site (which btw we had to rip off the .js stuff and reverse engineer the whole timer thingy), using free versions of everything..even though money wasn't an issue (what our client said). Same client decided to go with transhotel because it was sooooo gooood... OK? Why did noone heard of them then?
Anyhow, the api was xml based.. we had to send some xml that was validated against a schema, we received another that was supposed to be validated againts another schema.. and so on and so on..
...
...
supposed..
The API docs were nonexistent.. What was there, was broken English or Spanish.. Even had some comments like Add This & that to chapter xy.. Of course that chapter didn't even exist yet. :( And the last documentation they had, was really really old..more than a year, with visible gaps, we got the validation schemas not even listed in the docs, let alone described properly.
Yaaay! And that was not everything.. besides wrong and missing data, the API itself caused the 500 server error whenever you were no longer authenticated.
Of course it didn't tell you that your session was dead.. Just pooof! Unhandled crap everywhere!
And the best part?! We handled that login after inspecting what the hell happened, but sent the notification to the company anyways.. We had a conf call, and sent numerous emails explaining to them what a 'try catch' is and how they should handle the not authenticated error <= BTW they should have had a handled xml response for that, we got the schema for it! But they didn't. Anyhow, after two agonizing days talking back and forth they at least set up the server to be available again after the horrified 500 error. Before, it even stopped responding until reset (don't ask me how they managed to do that).
Oh yeah, did I mention this was a worldwide renown company?! Where everybody spoke/wrote English?! Yup, they have more than 700 people there, of course they speak English! <= another one of my ex clients fabulous statements... making me wanna strangle him with his tie.. I told him I am not talking to them because no-one there understood/spoke English and it would be a waste of my time.. Guess who spent almost 3 hours to talk to someone who sounded like a stereotypical Indian support tech guy with a flue speaking Italian?! // no offence please for the referenced parties!!
So yeah, sadly I don't have SS of the fucked up documentation..and I cannot post more details (not sure if the NDA still holds even though they canceled the project).. Not that I care really.. not after I saw how the client would treat his customers..
Anywayz I found on the interwebz some proof that this shitty api existed..
picture + link: https://programmableweb.com/api/...
SubRant: the client was an idiot! Probably still is, but no longer my client..
Wanted to store the credit card info + cvc and owner info etc.. in our database.. for easier second payment, like on paypal (which he wanted me to totally customize the payment page of paypal, and if that wasn't possible to collect user data on our personalized payment page and then just send it over to paypal api, if possible in plaintext, he just didn't care as long as he got his personalized payment page) or sth.... I told the company owner that they are fucking retards if they think they can pull this off & that they will lose all their (potential) clients if they figure that out.. or god forbid someone hacked us and stole the data.. I think this shit is also against the law..
I think it goes without saying what happened next.. called him ignorant stupid fucktard to his face and told him I ain't doing that since our company didn't even had a certificate to store the last 4 numbers.. They heard my voice over the whole firm.. we had fish-tank like offices, so they could all see me yelling at the director..
Guess who got laid off due to not being needed anymore the next day?! It was the best day of my life..so far!! Never have I been happier to lose my job!!
P.S. all that crap + test + the whole backand for analysis, the whole crm + campaign emails etc.. the client wanted done in 6 months.. O.o
P.P.S. almost shat my pants when devRant notified my I cannot post and wanted to copy the message and then everything disappeard.. thank god I have written this in the n++ xD
11 -
I am using this SDK and I came across a property "Orientation" of type int.
Why int? Is it an enum or something? Let's have a look into the online documentation...
"Gets or sets the orientation."
😣
Yeah, thanks. Very useful.
It's again that kind of documentation which simply restates the property name or method name. Who needs this?
So I tried to set the Orientation property to 1 to see what happens.
A runtime exception then told me that the only valid values are 0, 90, 180 and 270.
Well, this is kind of stupid but ok, I can live with that.
But ffs, put that info into the documentation, where it belongs!
5 -
- I am leaving the company, so you will work on my project.
- (looks at code) But there is no single doc string or any documentation apart from the installation guide.
- Yes, but the project is really easy to understand.
... I will just sit here trying to understand your code instead of doing actual work. -
You know that Elixir takes documentation very serious when you only have around 120 lines on a Module and 110 are from documentation.3
-
Django was the first web framework I learned. I didnt understood the praises for its documentation ... Until I started using Flask...4
-
So both my and my friends documentation for this project got rejected. It wasn't much of a surprise as we both have the same teacher who is very very strict on documentation. We are discussing all the documentation stuffs when he drops this:
Going to Africa and giving all children water is easier than getting this fucking documentation approved.
I fucking lost it xD. Okay, a bit harsh maybe but at least you get the idea.3 -
So I just found out that half the software requirement specification that I spent a good month writing, half of it may possibly be scrapped due to the client constantly changing their minds about what they want to do.3
-
Is it so hard to comment your code?
I work on collab projects here and there and both the comments and documentation are both awful, nearly always, there are some exceptions.
This is a plea to all those who teach anyone to program. "This performs a loop" is not a helpful comment, nor is "This sets variable x to 1" where the line below is "let x = 1".
The last piece of code brings me on to my next point meaningful variable names. If x is a variable that stores the age of a machine call it ageOfMachine or age_of_machine. Not aom, not x but what it actually is, modern IDEs and text editors will fill this out for you.
Finally documentation, a good friend of mine sent me this quote a while back, I can't find the image but "Documentation is like sex, when it's good, it's great. But when it's bad it's better than nothing." Your documentation should be good, a good pattern to follow is the Node.js documentation, it tells the function, what it does and what parameters it takes.
Anyway rant over; and I'm sure that this applies to people outside of this community only.5 -
Anyone else make the weirdest workarounds ever to trivial framework problems. Then read documentation to find out that there was a function for that...
-
Email chains, screenshots shared in google docs, two comments per 1k lines of code, and sticky notes are sufficient documentation, right? RIGHT?2
-
I want to get in the habit of proper documentation of my code, But i'm not sure how it's formatted, how it should look or how I should even begin writing documentation? Do I open a document and just take snap shots of my code and explain how it works? I'm a little confused. Do I take pictures of my UI and explain how to use it? Is it like writing a book?
5 -
Reading the Facebook PHP SDK documentation today to make a custom feed on a site. The documentation tells you how to do absolutely everything. Which is great in theory, but means you have loads to read to find the small bit you need.
Turns out I didn't need the SDK after all. Used simple curl request instead. -
Dear fellow project member,
I agree that most code should explain itself, but if you need to use a certain method which requires you to pass several different values of the same type and you just pass values as you like and then get, as you like to call it, 'unexpected behavior', then that is YOUR F***ING PROBLEM.
I DO know your thoughts about documenting code and I DO know you think documenting code only delays the progress, but if you for once could please CHECK THE DOCUMENTATION I WROTE, there would be no need to message me EVERY FIVE BLOODY MINUTES to complain about something that actually works when used right, just because you are too lazy to read the docs!
If you would do that next time, at least the time i spend writing documentation for our project would not be COMPLETELY WASTED! 😤
Kind Regards2 -
I'm a python fanboy, not gonna lie.
I love everything about it. It's clean syntax, ready to use out of the box-ness, convenient built-in functions.
The one thing I hate is the official documentation. It's ugly, hard to navigate and a cluster fuck.
But it has proper information, so it's fine I guess. tsch14 -
!$rant
"Always make sure to have good documentation in your code."
And I still struggle with this advice xD -
So I handed in my official resignation last week as I will be changing to a new job next month. So one of the last big things that I have been working on is a Jenkins server for the rest of the team to use and currently writing up the documentation for it.
However I haven't been told who I will be handing over my work to, but the bigger thing I feel is that even if I write all the documentation, no one will actually read it. Reason I think this is because I doubt anyone else in the team will even use the Jenkins server. The major issues are that no one writes unit tests and don't even understand what CI is!
So right now it feels like my final month of work will all be for nothing and makes me wonder if I should even bother writing documentation, especially if it isn't going to be handed over to anyone.5 -
Hate it when I spend more time on documentation than actual coding. I know documentation is for our own good. It still annoys me to death.6
-
I despise any service, framework or any software that has as its documentation a wiki. The wiki is always outdated, always links to deleted content, always has code examples that are wrong and always forgets any notion of best practices.4
-
Sometimes I think the only thing worse than undocumented code, is poorly documented code; I mean seriously, you're just teasing me at that point.2
-
Is making documentation in markdown recommended or word/other editor?
I also need to put some pics and codes.2 -
Work it harder, make it better
Do it faster, makes us stronger
More than ever, hour after hour
Work is never over
Oh the rant? This is gonna be a long one, and that was one of the lyric that stuck in my head for the past 3 days, Alive live album 2007 was glorious,
TL/DR, note to self, ALWAYS ask for documentation, and written evidence of any task & stories before start anything next time,
To start, death march was over, my team and I got some downtime(less work) for the past week, some of the guys were still busy with their respective stories (bugs, etc) but all in all it was not as much load as the past month before that,
It was peaceful and quiet, I was working bugs, some enhancement here, some enhancement there, it was nice for a change, until
One of the PO came by, asking if there's any spare dev, my team's tech lead suggests me as it's gonna be a front end work on web, good old HTML and CSS, and it's supposed be a task, not a story, I thought it's gonna be nice for a change, so I agree, the PO took me to the lead developer in charge,
Both of them briefed me, it's gonna happen in the apps (it's web alright, but in React Native, so no HTML and CSS for me), i was tasked to create 2 forms, and connect it with the microservice, "okay" I thought to myself,
Me: "Do we have the design for this?"
TL: "no but someone already made similar page you can either reuse it, copy paste it, whatever"
Me: *my bullshit senses are tingling, "that's one, what about the second"
PO: "I think the other team already made similar one too, lemme check, ah here it is, if it's all good I'll make the story for this"
TL: "okay, so there's that, can you start right away?"
Me: *tingling intensifies, "wait what about the flow"
TL: "it's simple, I will do this then it takes to your page, then this and that and that, and you do this and should be done, the MS is all there you just need to make the front end and connect it with MS, good?"
Me *hmmm intensifies, "ok let me check the available component first and see what I can do"
TL: "great, can you finish it by tonight?"
Me: *what the fuck intensifies further, it's fucking 6 PM, "nope, I don't think so, there's always complications when handling forms, not to mention copy pasting stuff"
TL: "it's ok, at least finish one by tonight"
Me: "..., we'll see"
-next day-
Trying to reuse the form for the first page is no good, I had to duplicate the components, first one is working fine, the second template is almost done,
TL: "dude how's it going? It's been a whole day"
Me: "first one's finished, second's underway"
TL: "can it be don.."
Me: "today? Nope"
-next day-
TL: "dood, is it done yet? It's been two days, what's left on the progress?"
Me: *for fuck's sake, "I just need to figure out how to connect between the first and the second and it's done
TL: "okay cool"
[different PO came by]
PO #2: "hey, hi, sorry, what's the progress on this?"
Me: "uhh hi, just need some unit test and it should be good for PR"
PO #2: "cool, keep me posted"
I finished, about to put a PR, I need the story ticket, I asked the PO and the TL
PO #2 gave me the ticket for the backend work which the TL is working on, no mentions or specs for th front end
TL gave me a ticket which was just created shortly the moment after I asked for it, only title and no description
Me: *shit, this will be interesting
Sure enough, the tester who is doing smoke test on my branch threw a fit, where's the spec, where's the design, where's everything, how is it supposed to work, the flow, the typecheck, translations, etc
The news came to be heard by the design & product team, and they came by, apparently no one knows what the front end was supposed to do, all everyone know is just the back end part,
In the end, it goes apeshit, everyone are confused, everyone have different understanding of the story, but at least what I've done doesn't went to ashes, after explaining everything to the design team, they decided that let it be, but there's might be some minor changes on the layout,
And then I began to understand why this TL and PO #1 had somewhat bad rap, while I was stuck with PO #2 trying to explain the relation between my task and the backend user story,1 -
My boss asked me two days ago to fix some errors in an application. From the errors I saw it would be a 5 minute fix. I fixed the problems just now because there was no documentation on how to set it up.
After setting it up it was just changing a value from true to false...
I ruined two days just because there was no documentation. Please everyone, I know writing documentation is boring but at least write some documentation on how to setup a project.3 -
Why do some developers write the official documentation with low interpretability and a high number of technical terms? It does not look cool if it does not serve the purpose it was made for - Helping us understand your software!!!
-
Our documentation is currently stored in a VM image after the host died, meaning we have no access to anything - good times!5
-
I had this a while ago. Started a new project at my study (Application Development) and started working on the documentation. After rewriting parts of the documents for nine weeks (10 weeks for every project where I study) because they were not approved by my teacher because they didn't fit her 'personal preference/style', she even had the guts to tell me that I am a bad programmer because the application was even less than half complete. She only gave me one week to create the application that normally takes at least five weeks.5
-
While I was still in University I didn't valued much the importance of comments and documentation, mostly because my projects were small and I was working on them by myself. Frankly, writing comments felt like a waste of time those days.
Now that I'm a junior developer working with an existing code base and together with other devs I couldn't be more grateful seeing those green lines of human readable strings. Without them I would have struggled more and probably been less productive.1 -
Was delaying learning a course for quite a long time (felt boring). The finally got the stuff by reading the documentations !
Tell me I am not the only one who thinks reading documentations is way better than taking course (in case of proper documentation ofcourse)2 -
Sup with all these people in the office arguing that writing documentation is pointless because it will just become out of date? I even heard one dev say it'd be so problematic that the company would need to hire someone full time.
That sounds like BS to me. Sounds like some people culturally think documentation isn't cool. That maybe they don't know how to do it.
So, I'd like to hear opinions on the topic. Mine is that documentation is useful and even if it gets out of date, it provides some value.
What's better: out of date documentation, or no docs at all?10 -
The best kinds of comments:
/**
Gets user CC info datas.
*/
public Object getUserCCInfoDatas() {}
If you really want to outdo yourself:
/**
Gets user CC info datas.
@param someshit Outdated docs ftw
*/
public Object getUserCCInfoDatas(String unrelatedToDocAbove) {}
Honestly, no documentation is better in some cases. At least I can't be angry about their shitty quality... And they don't waste my time.3 -
When you click on the github wiki of the API you wanted to use and it shows you the "Create the first page" banner....
Guess I'll have to find another API with proper fucking documentation.2 -
In the middle of coding: "Too into code to document properly. Will document later."
Two weeks later:"What the actual fuck is this code doing?"
2 -
PM: "Can you take a look at this app and see if you can find why it's producing errors and fix it"
Me: "Yea sure, can I see the documentation so I might be able to understand the system and why it's doing that?"
PM: "There's no documentation" ... "Also it was cowboy coded by an intern" -
Work is requiring me to bust my ass, I am salaried, it is writing documentation, and my FUCKING LEFT EARBUD DIED!3
-
I've seen several rants on here about poor documentation on great libraries. Well I just spent 9 hours in a car today and I realized that even the ones that have great documentation absolutely SUCK at being mobile friendly. I'm no web developer but how freaking hard is it to optimize your stupid website for small screens??? There are a million frameworks out there you can choose from PLUS it's almost entirely text so it can't be that hard!! I have to zoom in about 300% to be able to read it, then I have to scroll back and forth because it no longer fits on the screen.
-
Yesterday i realised the importance of documenting everything step by step . I was told to port an driver/application that we made for linux 4.1 to a 4.9 kernel . Eventhough i did already port another similar application to the same , didnt remember what are things that i did.. Thank God ..If not for the constant pestering of my colleagues to document each step.. I would have been stuck in that island for 2 more days ..1
-
Yet another Hacktoberfest tshirt
From Auth0
Received by improving documentation and the product itself
(The tshirt is darker than the image)
3 -
Me: "Need help with build config problems, please help almighty documentation page!"
Docs Page: "Nah fam, I got 4 headers about problems with no text, a blank code example, and 2 error 404 pages."
And that's why I don't like build pipelines. -
I fckin love it when you start working on a new project in a new team and the 5000 lines of Angular code are acompanied by 0 documentation.
-
For my school project I made an Django app and after a while I implemented more and more functions, but now the code is unreadable and I began hating working on the project. So I rewrote it and added documentation and now I have a beautiful application with documentation and clean code!1
-
Team Leader(TL): So you finished the sql scripts and stored procedures?
Me: Yep!
TL: And properly formatting the front end to look exactly how we want it.
Me: Yep
TL: Well we waiting on feedback from the boss so i guess you'll have to do the documentation.
Me: I hate documentation, please give me anything else
TL: It's not a lot dude, you can do it.
Me: Didn't one of the intern's and the database admin do it already?
TL: Yes. but you can take both of them and make one complete one.
Me: *You just don't want me to work on my own things you FUCKER* Fine, but don't expect it to be done this week.
TL: It's Tuesday, why not.
Me: Because i hate dcumentation
I FUCKEN. hate! documentation.4 -
!rant
A snippet from the official W3C service worker documentation:
"This avoids the problem of two versions of a site running at the same time, in different tabs. Our current strategy for this is “cross fingers, hope it doesn’t happen”."
https://github.com/w3c/...1 -
I started creating a complete API documentation for devRant. What do you guys think?
It's far from finished yet, but I'm heavily developing it right now.
Here's the repository: https://github.com/ThePlatzhalter/...
A preview is available at https://htmlpreview.github.io//...25 -
I need counseling to fix the distrust in my life.
Distrust of official documentation.
Why can't I trust it works the way they claim? The pain it causes...3 -
You may not like but dokument everything in your project. It needs its time but it can save your job.
-
I have suddenly started liking writing word documents rather than writing code ...
What’s happening ??!? What’s wrong with me !?!5 -
So I guess I really need some sleep. I'm rushing to finish a project for work and literally wrote the same documentation twice. I realised after I tried to save it and it said "Pagename already exists". Its almost fucking identical. I'm so stupid.1
-
Dear Java library developers. The javadoc is not an excuse to not write documentation.
Signed,
a very annoyed golang developer -
If you're not going to update your API documentation please just delete it. I spent two hours trying to use the example only to discover SECRET REST PARAMETERS that solved my problem.
If it weren't for the hero bitching in the comments about the missing documentation I would never have gotten this to work.2 -
WooCommerce is shit
Just try to find anything in the documentation on their retarded website and you will get what I am talking about.
A billion of unstructured links. With absolutely no sidebar or table of contents.
IMPOSSIBLE to find any fuck there.
It is far easier to build an e-store from scratch, than to customize their ugly monster.
Now look Laravel or PHPunit documentation to compare how it should be.
-
Do you recommend Vue Press for documentation? Or do you know a good alternative?
https://vuepress.vuejs.org/2 -
Got into the job a week ago, was asked to do a documentation of a project. It started 4 years ago.4
-
No documentation, even if it's for personal private projects.
I still can't wrap my head around code I made 2 years ago...1 -
Dealing with a C# SOAP API with absolutely horrible incomplete documentation is insanely frustrating, especially when C# isn't one of your familiar languages.
I want to do bad things to the developers of this company for not supplying proper thorough documentation on how to use their API.9 -
When you find that one critical piece of documentation that you need causally mentioned in a github comment somewhere. They'll never know how happy they made me :D
-
A software is as good as its documentation... a crap documentation makes it un usable... how so ever good your software is...
-
Taking over development of a system from some other guy who just straight up dropped it with zero documentation. The code looks like he wrote it after watching some getting started tutorial. There is no structure. Some methods and statements are just empty. And he spelt 'connection' three different ways in the same file.
God help me...1 -
When reading the documentation could have saved you hours of debugging.
"How nice, there's actually a property for that..." -
An example of bad documentation? Unity. It has a list of poorly described methods of deprecated classes. The only reasonable documentation is the community. Docommunitation.10
-
One of the senior devs just showed me their documentation AND IT'S A FUCKING ONENOTE FILE WHERE EVERYBODY JUST WROTE WHATEVER THEY THOUGHT SHOULD BE WRITTEN DOWN IN RANDOM PLACES
Atleast it's some sort of documentation I guess.2 -
Question to the Java developers here:
Is it always the case that Oracles documentation and actual implementation don't match?3 -
You know what pisses me off? When I don't know what a constant is used for so I check the documentation and this is what I see:
2 -
TLDR: fuck this plugin.
Longer version: I recently had to implement an external Vue plugin to upload files. That gave me a good headache already, mostly due to the half Chinese, half Google Translate English documentation. I now found out that testing the implemented component may be impossible. Turns out it overwrites the $route and $router variables and makes them read-only. Which won't even let me create a shallow mount of my implementation. Fuck this shit, I'm getting a drink!4 -
Last year I wrote a sudoku program which did solve easy sudokus but messed up on harder ones. I had got bored after a bit and forgot about it until today I thought I'd rewrite it using new stuff I've learned since and make it work properly.
So I opened it up and look and I'm like 'WHAT!?' because I don't understand what I wrote. After a bit I start to get the idea and see that it was kind of smart even if long and complicated.
If anything, it shows how much my documentation skills have improved.
Now I just have to work out how to redo it in a way I understand.7 -
You know that moment, when you look for something on wikipedia, and after few hiperlinks you are reading about influence of penguins on Mars' day length or othen nonsense?
Just happened to me like 4th time when reading Django documentation. It is so well written and easy to understand, that I just click and click and want to go deeper, and then realise I have to read what I need, because I never ever got to it in the first place.
Gotta love the people who make such docs. I never could, and prbly will.1 -
Just switched to the "!" for Python Struct because it was a better description. Then i saw the documentation on this. A "little" bit offensive.. 😁
-
API provider: include a signature based on these fields in this order. DO NOT ENCODE IT!
Implementation works a while, then..
*a wild apostrophe appears*
Signature no longer works.
API Provider: "oh, yeah we escape those."
Arrghhghghghhhghvhxmchsoxnsoxnwl
Not only is it a poor design for signing payloads, the documentation is shockingly poor in it.
Even the implementation example (which is supposedly from their code) doesn't account for any type of escaping or encoding.
Before anyone asks, I can't into details about the implementation.3 -
Googling for Angular (>=2) documentation and finding AngularJS instead feels like cancer.
If Google was going to "update" to what is functionally a new framework, they should've named it differently instead of trying to piggyback on the popularity of AngularJS. Sure, there's similarities, but let's be realistic here.7 -
Spent 2 hours wondering why Unity Engine sees my 2 joysticks as Joystick 1 and Joystick 5 (or 6 depending on a UBS port).
Turns out, for some reason, Unity remembers ALL the ports that were ever used (even with the usb extender). That's documented...exactly nowhere. Ok, at least I figured that out, but what am I gonna do about it? Nothing, there's no way to change the order.
So after a quick nervous breakdown, and a cigarette break, I decided to build and run the game, just to see how it looks, and...what's this?
Everything's working! Unity removes all the joysticks from it's array and puts only active ones in the right order and that too is documented...NOWHERE!
Ugh... Unity I still love you, but god damn, GET YOUR SHIT TOGETHER!!!
Needless to say, this day is an emotional roller coaster.1 -
I seem to be the person that tries to implement the default solution using the default HowTo - not going fucking anywhere because shit fucking breaks somewhere in the process.
Fuck people who advertise their software "as easy to install and to maintain" not maintaining their documentation.
Can I be a fucking user, oblivious of the world around me, just one fucking time?!
Also, coffee makes me fucking irritable atm.
Fuck everything.
(I probably should work in QA. Oh wait, I did something like that before.)3 -
Fuckadoodling finally!
After 3 days of digging through the documentation of CraftCMS and Yii Framework I got the hang out of how these Controllers, Actions and other RESTful api stuff works on Craft3.
As some of you may have noticed, I am a big fan of CraftCMS (v2) since it was introduced to me. A few days ago we discussed a new project and the option go for Craft3, as it has been released for some time now.
The changes from v2 to v3 are huge... I didn't expect to almost reach my limit to give up on it!
But since the RESTful routes finally work, with proper data serializing and all, I will now go drink a Whiskey or ten and wish you all an awesome, client-disturbance-free, decadent, beerful weekend!
Cheers mateys!
🎉🎊🍭🥃🥃🥃🍻🍺🥂 -
The documentation for the matplotlib python library is terrible for newbies.
There is a "Tutorial" section, but the thing doesn't even explain what you can do until you get to the 4th section!
It starts off with some confusing examples, how to change the appearance and only at section 4 do you actually start to get an introduction to the different components you might want to use...
At some point you finally realize, most of the stuff that is shown can be omitted because the .pyplot module is all you need. -
If you have any project (personal or not, doesn't matter) that does not have proper code comments and documentation and you don't want to make one because of the effort (maybe even "wasted" effort), think again. When commenting on a wall of code to say what it does, you may find a better way of doing what you have to do, possibly increasing performance, or improving security.
I have been able to do better input sanitization for a method on a personal project of mine because of this.
Don't use the amount of effort for proper documentation as an excuse not to make one.2 -
When online documentation is nonexistent but everyone expects you to use the technology.
Well alright then!
2 -
Feeling sleepy reading v4l2 documentation.
Opens devrant for a few minutes.
After 45 minutes of scrolling and commenting.
Shit, I need to get the driver working today.1 -
Dear developer guy who wrote this documentation node!
You're a developer yourself. Don't you know that inverse psychology is something you should avoid, because it will not work?
Thanks!
---
Okay for real, why shouldn't one parse Build.FINGERPRINT on Android? I was looking for a way to determine if the device is an emulator or not, and came across a solution using this, and read the documentation.
3 -
no matter how many books i read about a particular technology, if i don't read the official documentation ( no matter how large it might be ) of that technology, i always feel dumb and stupid
-
Started a new contract:
Dev: "here, take this draft document containing a rough explanation of the requirements and write this service that exchange messages with these two subsystems"
Me 😐"ok"
-- couple weeks later --
Dev: "oh btw, you should go through ALL the fields in those messages described in the 'documentation' and double check them because we use millimeters and they use meters, we measure milliseconds and they use seconds. You should handle conversions when you deal with those messages"
Me (in my mind): "fucking son of a bitch! Why didn't you tell me this little piece of information at the beginning so I could have accounted for that instead of bloating the code now with your spaghetti style, full of horrible hacks, ifs and workarounds?
Me 😐: "sure, I will"
(don't worry, in the end I managed to find a clean solution for that 😉)1 -
At work we use "Mythological Documentation": mystical features and obscure workarounds are verbally explained across generations of developers that come and go, keepping the knowledge alive.
-
Documentation at the end of a 3 year project is like writing a blurb with only titles of the chapters... You better understand the entire project !! Good luck to the new guy.. Lol
-
What do you prefer in documentation for descibing methods? Why?
My prefered option, because it gives you the most important information easily:
1. `bar* foo(foo*, int, int)` does xyz
or(I find this misleading(looks like a variable)):
2. `foo` does zyz
or(this I too find misleading, looks like foo takes no parameters):
3. `foo()` does xyz
or(I find this inelegant):
4. Function `foo` does xyz
I thought 1) was the best options until I got a lot of complaints for it, so I'm asking this.
Is your choice language dependent?2 -
Loving inaccurate documentation...
And it's from a big company as well!
Reset value: 0x0000007F
I didn't get it to work for several hours.
And then I checked...
The actual value it gets reset to is 0.
Just 0. -
Starting a new side project and I am determined to do it right.
Just finished writing the features list and now I'm writing the documentation. Not written a single line of code not, nor even created a repository.12 -
So on the weekend I picked up a project again I started 6-8 month ago. Due to automated scripts and documentation I could reach the point where I left of month before in a few hours. It's nice when writing docs and scripts pays off :-D
-
I actually like writing documentation. It gives me a break in a different pace, gives me time to refocus on what I've built and hopefully make it useful for others as well.2
-
"Go check out the EAGLE documentation so you know how to properly parse its generated xml files"
(The whole docs just says "sorry, no documentation" every fucking where, not just the part in the picture...)
3 -
Fucking hell the AWS IAM documentation is confusing as fuck. Trying to set up a fucking role is harder than cutting a rock with a fucking spoon.
And who the fuck thought it would be a good idea to allow a CLI user to run any command he's allowed to without any form of authentication??
Oh, set up MFA for the CLI you say? Good fucking luck with that, if you ever manage to figure out how to set that shit up!
Fuck this shit!2 -
knowing what an api does and which arguments it expects just by looking at it...it would safe so much time for me esspessialy when i haven't used the api or language in a while2
-
Love writing comments, hate writing documentation.
Ugh, I know it is needed but just don't care about it as much as the code/comments which is a more direct 'here is what this does' approach. Writing idiot proof documentation sucks. Any little change? Have to remember to update the docs. Yeah, not happy.1 -
Anyone in here have experience with UML in the real entreprise world?
As a student I've learned a lot about documentation and software architectural design, I've worked 3 different places and worked with customers that were developers and all of them seemed to not really do architecture and documentation that well. Personally I find having an overview/guideline for bigger project really helpful
how come you don't see better software documentation and UML out there?
Maybe I just haven't found the right place yet4 -
Wiriting documentation is the single most boring thing I can imagine.
Fuck, it'd be more entertaining watching paint dry, or seeing the grass grow.7 -
Is it me or most developers just write code so it compiles and passes tests?
No documentation, no standards, no "good practices", no"good design", no software principles, no performance analysis, nothing.1 -
Reading documentation for 3rd party software... come across a code snippet which references a class. The class is spelt correctly in the comment but wrong in the code!
What??? Surely if you're going to get it wrong it would be the other way round :/ -
Spent seven hours reading source code at work yesterday. The little documentation I was able to find alternated between English and Spanish. And some of the things I saw... Straight out of a horror novel.
For example: NUMBER_2 * NUMBER_60 * NUMBER_60 * NUMBER_1000 to get the number of milliseconds in two hours.
Or this super contrived method which capped the registration age at 100, which now caps it at 102 anyways because they use hard coded values for the current year. Took me 15 minutes to find out what "fixYear" (this method) did.
No wonder I got home and crashed in bed till nearly midnight after that... I swear that was harder than a university Calc final...3 -
Well, after about a grueling week of messing about with android and firebase and let's not forget that !gorgeous Google documentation, I managed to push out my first app!
It's based on Learn X in Y minutes, which I am a really big fan of, and it's basically a mobile reader version of it.
It's available here https://play.google.com/store/apps/...
And the source code is also available here https://github.com/modelorona/...
I welcome any critique. I'm positive there's some stuff wrong in there, would be obvious to you but not me :)
And happy late new years! I actually released the app at 3:50 am yesterday :D8 -
Does anyone have any recommendations regarding self hosted documentation/"note taking" platform/server ?
I would like something with markup support, I've looked at the awesome list for self hosted services on GitHub... But there is a lot... So does anyone has any experience he or she is willing to share ? 😇
Dillinger looks nice (https://dillinger.io/) but no idea if I can save to my server instead of locally/cloud services...4 -
Seriously is kivy just lacking documentation on purpose.
You want a tutorial will just look at these apps other people have made I'm sure that will help.
No looking at some game code doesn't give me any ideas on how to create a basic form or a nav drawer.
Seriously are we supposed to fucking guess?
At this point it would be easier to write a gui framework than learn kivy.5 -
You explain something exactly. Write extra documentation and even do tutorials and videos for the approach.
And then others come along and think they want to do it completely different. And only because the colleague before them has already done so. -
Isn't it fun when you are given a library or framework and that in order to debug it you have to use some hacky way of hooking the code to a special instance of the project?
Even more fun: the developers by default don't debug the project with tools, but rather with logic. Ok, that's a good way to debug but it shouldn't be the only way to debug. I don't want to go back to the age of coding on paper. At least give me a stacktrace that's halfway clear on what's happening there. Even worse is when the framework doesn't document its own problems! stacktrace.someMagicalMethodNoOneKnowsWhatItDoes(). Having to read the even more mystic and overly verbose documentation! You're just left there trying and guessing shit, even for the senior devs!
And do you know what's more fucked up?! Fucking using println() to debug!! And they take this shit seriously! I don't understand how these people call themselves programmers. No breakpoints? What the fuck, man!
Just give me Visual Studio for fuck's sake. I don't want to code in a broken IDE with a broken framework. Development on its own is already hard enough, so don't make it harder by giving me crappy frameworks and crappy IDE's that only work half the time.
Debugging without a debugger, with broken IDE's, with broken frameworks, I'm sorry but that's just not for me. And then the framework dares advertise that it 'lets the developer focus on business code!' (how many times have you heard this crap before?). Right, the only thing I focus on constantly is trying to figure out why their broken framework doesn't work.
Arghhh. -
Just like there are many programming courses, bootcamps etc. there should also include documentation bootcamps and courses1
-
Today is one of those magnificent days for my code. One of those days where I stumble up on the weirdest bugs and pull a fix out of my hat barely looking at any doc. One of those days where I find out there is a very tricky flaw in our project design and yet I end up finding an elegant solution to circumvent future problems. One of those days where I find the informations I want even though the documentation is the worst I've ever seen.
I love that productive feeling. -
Ok, so i havent been coding in a while, but now i have somthing rant worthy!
So i was helping a project and THERE WAS NO FUCKING COMMENTS, I mean what the shit! Atleast add some comments its as easy as typing //, what has come of this world?2 -
Serious question:
Is there such thing as too much documentation?
I've got an ASP.NET Core app, and things got... weird... for necessary reasons. Lots of reflection happening. I ended up building a custom framework for our archaic piece of shit database because literally nothing else would fit or even support it.
I expect whoever else would maintain it after me won't even be familiar with C#.
Would it be overkill for literally half the lines to be docs or comments?7 -
Spent an hour today deciding if something in my framework should be called functions or methods... Decided on methods and had to rewrite half of my documentation.... Productive day...
-
I spent the last hour of writing the documentation for my javascript class. I should be proud, but all i feel is tiredness...
-
From Documentation:
"A SHA256 HMAC is created outside of Bronto. If you need help with this step, contact one of the developers at your company."
Yes because, cause every company has a developer.
*Only developer at company* -
yet another rant about shitty documentation, this one isn't readable without copying it out somewhere else.
How does someone decide this is good enough to post online, i swear some people don't proof-read anything anymore
1 -
I have become the only thing I always hated in a developer. Building a project without a proper documentation.
As a solo developer in a company where I have to do database architecture, front-end, back-end, testing, NETWORKING (I am the most ignorant guy when it comes to networking), product design, there is no time for documentation.
But hey, I have structured the project, files and functions (with comment, parameters type and return type) properly and I understand what I've done even after 4-5 months without touching that specific project so I got that going for me which is nice... I guess.3 -
Documentayion my ass!
Whoever wrote that documentation for qutebrowser: You fucking apathetic shit nugget, you have a fucking feature over there and all you do to fucking document is to hide it within a indifferent example? How the fuck am I supposed to configure that shit if it isn't even mentioned wheresoever? You're example simply assumes that the reader has all the background knowledge and nostly lack relevance as much as IT in my highschool. Read that shit yourself and tepl me if you can find out how to configure this BS3 -
Spent about 40 minutes trying to figure out why my stupid events were not tracked, something about CORS
so digged into the htaccess file and added the correct headers but the header value was being appended although i was setting it.
So I figured the "tool" i am using is setting it too but only when I set it, that was weird.
So on to to its github I went, someone mentioned there is a CORS setting in the UI, so I added the domain i wanted to allow and done, it fucking works.
Read the documentation kids, sometimes it is useful. -
Once upon a time aka last week,
Was trying to fix an industrial automation software coded in Codesys. My company's standard library is riddled with bad documentation with a mix of English and German terminology.
Had to find out why a program kept crashing the program upon start up. Long story short and many stressful hours later, I found two functions in the standard library that caused an endless terminal process loop. Had to wrap the function in an 'if statement' so it would only run once. Function should have done this by default. -
Related to the project in my last rant...
Project got delayed for about a month in total because the API for the payment gateway wasn’t allowing charges against stored cards. Could save, modify, and delete them, but no charges.
After a week of trying to get things working based on the documentation, I get in touch with the vendor (great people) who file a support request with the people running the processor so we can see what’s up. Long story short, that amounted to 3 weeks of getting ignored until the vendor raised hell on my behalf, only to get the following reply back:
“You’ve been using the dev credentials, try it on live transactions instead!”
Thankfully, we’re able to move the customer to another processor under the same vendor, where I already have all the requests figured out...2 -
Trying to learn <insert name of programming language>...
Can't find any useful documentation or examples.2 -
Just made a damn fool of myself with a client. I handed off three projects and they had no idea what they were for and neither did I. My boss gave me these months ago. No code comments, no documentation, just some stored procedures they wanted me to actualize.
The best I could offer was to promise the client I would send a description of the projects to them as soon as my boss gets them to me. Fuck. I thought the client would know what they asked for when I showed them, but fuck me, they didn't remember. So embarrassing. 😡😡😡 -
Ok I fucking give up, does anyone know of any tutorials on adding custom languages and syntax highlighting to VS code, I followed what little readable documentation overlord Microsoft has given and still no fucking clue, help!3
-
Writing documentation is one of those tasks that most developers don't like doing. Especially when it comes to writing in say a Word/PDF file, an online wiki, or Confluence. It's time consuming and a pain in the ass.
But even if you don't like it, at least write comments in your source code! I hate having to keep writing "Write the PHPDocs for this class/function" in every pull request that I review. It's wasting my time writing such comments when it's such a basic thing to do when writing source code.2 -
This is an example if stupid documentation.
//Just like magic
try {
....
WTF! THIS IS PROGRAMMING, NO FUCKING MAGIC OR MIRACLES HAPPENS.1 -
Now let me just throw away most of this pre-work documentation from the PMs and do it right the first time.
-
I am really fed up with people emailing me asking about how they can use methods of a library I wrote when the answer is literally in the f***ing JavaDoc. At first I thought it might be me not being comprehensive enough in my doc, but when I literally started sending copies of what I wrote there and got a lot of "Thanks that makes it clear"emails I became really fed up with the laziness of some people. I find it disrespectful to my weeks of work for someone who wants to use it to not read a few lines when in doubt.1
-
Dev: "read the documentation i write its simply easy to understood"
Me: Yeah I can figure that much. -
Fuck this documentation is shit! Param names aren't correct and some API's expecting a different parameter than it is even named for!
-
Apache Jena Documentation is SAVAGE
when looking through their Node documentation I could sense the sweat and rotten despair of the devs.
The documentation can found in https://jena.apache.org/documentati...
1 -
Writes good code because "Good code is it's own documentation"
Ends up documenting someone else's code. :( -
NPM modules are supposed to make us save our time, but very often, after hours and hours of juggling I end up write by myself those fucking functions.
And I'm not talking about unknown packages made by a bored guy in a lazy Sunday, I'm talking about fucking well known modules like passport. OH MY GOD. How much sucky is the passportJS documentation? There are fucking hundreds of options and they are not referenced anywhere if not on StackOverflow. When you login in a website thousands of things can go wrong, why the hell do you always send that shitty 401 and you don't let me control the code? They are two fucking days I'm trying to fix it and I realized I could write that function in 2 minutes if I just didn't use passport. FUCK7 -
Providing a nice Readme.md file with your open source project is never enough. You need to have a beautifully designed website for the documentation to go with it, oh yes sir!1
-
Yet another probably final Hacktoberfest swag
From Umbraco
Received by improving documentation
Thanks to Umbraco for sending stickers which were missing in my pack ^v^
-
So I use Git intagrated in Visual Studio for the project's repository at work. But I don't like using it because I always used the command line to do stuff on my projects (including those at school, plus last time I used a GUI, I managed to do a merge without being conscious about it).
Why can't I change ? Well, because the proxy block every download link. Or almost.
So a documentation that was updated like 9 months ago was explaining things, and mentionned Git by provinding links to download the bash version. Happy, I click on it and try to download it.
Proxy blocked it.
Just fucking update your documentation1 -
Oh god why... Why is it that every time I work with software defined radios, I keep on having to rely on not just incomplete, but at times misleading documentation 😩
Last time was GNU radio, with the doc telling me that I could define an input for a processing block using either a type or a (type, size) tupple, only for the actual code to scream at me in confusion upon my passing a tupple.
Now is that other SDR's SDK, which, as if being built upon eclipse wasn't bad enough, managed to make its serial communications confusing. Why can't you just let me set a callback to rx interrupts, you daft punks...1 -
I fucking hate documentation.
It's been 5 straight hours I've been preparing documentation for the "In-House Project", because apparently it carries the grades which is necessary for me.
Fuck this shit...2 -
I would like to understand xcb library by looking at the rofi (dmenu replacement) source code but there is no code documentation. How do you guys deal with non-documented source code (supposed to be easy)3
-
Our team has to add some features to an existing application/platform. Its a mobile application with a server handling all the logic and a database for records storage. Fairly big project, a few 1000 lines. Ohh and did I mention that there is absolutely NO DOCUMENTATION???! Why on earth would you even be like ohhh let's do this project but write absolutely no documentation for it! Why???1
-
!!rant && !documentation
Hm, let's see what a semi-beginner can find as a project in Python...
Oh, an API Wrapper seems interesting! *full of joy*
Okay, let's look at the documentation...
HOLY FUCKING SHIT. IT IS UGLY. IT IS INCONSISTENT. IT IS INCOMPLETE AND WRONG. WHY THE FUCK, AREN'T YOU STUPID ASSHOLES CAPABLE OF WRITING DOCUMENTATION FOR YOUR API?
HMMMMMM?
YOU STACK OF SHIT.
IF YOU HAPPEN TO CREATE AN API, AND DONT DOCUMENT IT CAREFULLY, I WILL FIND YOU.
AND KILL YOU.1 -
Is there any simple documentation editor that allows html export? I found this template: http://surjithctly.github.io/docume... and could of course just write myself something, but is there anything out there that produces such similar/simple docs?2
-
Enterprise software companies that can't take the time to include even a bare bones admin manual. Scattered documents don't cut it guys.
-
Just started working on Alexa skills ,
And I must say , feel like a dog lost in a pool of balls plastic balls, while am chained to a pole. So much I can do.. but there’s no documentation as to how things work
All the docs available are old, and I didn’t really understand how things are working5 -
The only thing worse than having to write documentation as you code is procrastinating it to the end...2
-
Fuck undocumented shit!
I was wondering how to use this one method of the "interface". Googled the name of the program and the specific method.
Got two results.
From the same page.
It's a comment complaining that this shit is undocumented and doesn't work.
If you build something that others use, please, motherfucking please, document your code.
At least some auto generated javadoc, how hard can it be?
You are using the atlassian suite for everything and you have confluence so use it already! The only documentation that actually exists it about a hundred years old, totally useless and covers about 1% of what your product can do.
I like your product but fuck me sideways your documentation sucks balls! Fuck!
That needed to get out. -
I didn't think that it could be worse than in the companies I've been previously working at (last one was good btw)!but the current company has a code base for a website made in grails with an angular app and no existing developer knows how this site works - and there isn't a single comment in the code either. There isn't any other form of documentation either D:
-
That feeling when you realize that the REST API you were trying to consume apparently does not provide a query flag to get for a more detailed response making you think you'll need to fetch one list of items and then fire almost 1,000 requests really does not compare to that feeling when a colleague points out that the REST API in question does in fact support the flag AFTER you implemented the roundabout way.
FUCKING HELL!
I just didn't realize that I could click on GET and POST blocks for the metronome API documentation opening up a frigging pop-up. (See screenshot.)
Why couldn't the information have been more upfront? Only a cursor change on hovering the area could make one thing to click there.
Oh how I blame their lack of a user interface for my blindness.
I thought that it was just a basic documentation that only told you which endpoints exist and expects you to learn by trial of fire. So I searched the interwebs and on their support forum I found an old issue making me think that my round-about way was the way to go m(
Even worse, on the support forum I cannot even leave a comment warning the poor souls comming after me that they should not do the roundabout way as that issue has been long closed.
If you want to see it yourself: https://dcos.github.io/metronome/...
-
Wondering is there good designed template for API Documentation.
Or is there any good tool to generate automatically.?3 -
Why does the documentation in the website for API doesn't include the optional parameters to use?
Why are you making my life harder!
Good thing their github.io docs has the documentation for the parameters I needed.
So, why not include it in the official documentation?! -
Been working on integrating mail gun into the MVP of the webapp I am creating. Couldn't figure out why I kept getting a 400 response. Check the mail gun documentation and realize that it's expecting post parameters not JSON...
Well there goes those 5 hours. -
Documentation-driven development, we need to start treating documentation on the level we treat code. Thoughts?2
-
LONG MS WORD NIGHT DETECTED
I have to work on a high level document, low level document, SAC document and a use case script for me to get QA approvals.
**CLOSES EDITOR **1 -
Client complains not enough documentation. Wants an arbitrary number of pages in a document on our modules. Wants more uml diagrams. They are going to get so many uml diagrams!
So complex they must be right, because nobody can read them. Sick of doing this draft after draft after draft... -
When the documentation suggests you use composer to install swiftmailer so I can use sendgrid.
Even though I can install composer as an extension and sendgrid is integrated within the portal it's down to me to work out the azure cli or is it a powershell cli or is it bash?
Echo gives kudu error, oh well if there's kudu why am I using composer?
Grrr azure you don't make it easy. -
Hopefully, simpler sintax.
And better documentation for every language/framework. Especially for the devs who are just starting, don't write documentation assuming everyone has been working with your framework for years!
That last one was more a rant than answering the actual question, but I needed to say it. It's been on my mind for a while 😑2 -
If what I'm trying to learn is visual, video tutorials are useful. When it comes to programming, it sometimes wastes my time. Watching a 5-minute video to accomplish one simple thing? I could never get that time back! You can spend half of the duration of the video introducing yourself but I am already frustrated. I prefer documentation and hands-on most of the time. Just sharing my thoughts. Thanks.3
-
Today, or wednesday (can't do anything tomorrow, family is coming over) I'm going to start writing documentation for my project.
Problem: Never wrote documentation before.
I only have the database done (still need to write the migrations and seed, but the structure is done). How do I even write documentation for a bunch of tables? I guess I'll learn that this week.
Wish me luck, I'll need it!! -
I'm finishing up some software I designed, any tips for writing documentation for non tech people?5
-
Recently I've been tasked with setting up of a small /mid-size infrastructure and I've been documenting things like infrastructure design, network configuration all the way to playbooks and cluster configuration.
Since I just started with this, until now I have been doing this in a Google doc / some spread around markdown files. I would like to have a better way of having this documentation hosted internally..
I have been playing around with local installations of rtd, gitbook and mkdocs. So far, I've liked the simplicity and customizability of mkdocs.
Any other options before I commit myself to mkdocs?2 -
!!rant
Elasticsearch! First time touching it and need to find out on my own how to build an index that allows a weighted multi field fuzzy search on four fields where two needs to be full ngram, one ngram on the words and one standard search + not index any other field. The documentation is horrible! Just realizing that this is what I need took me 2 days!2 -
Integration of with another web service.
The only documentation it's a Skype chat.
😝😝😝
Save the chat content as text: It's the bible of this service.
Can someone write a text on the stone for future needs?
Please help me !!!!
2 -
Community Question:
I'm on a lone-project for work. That means I have to make a design plan and documentation. I have zero experience with this, anybody know a good example on the web of either of these? Much appreciated!2 -
I took over an application that consisted of 4 MSSQL (2005 at the time) databases, hundreds of tables, thousands of stored procedures, maybe a 1/4 of them actual still being used, external links to more than 20 other databases (MSSQL, Oracle and DB2) which all ran from a single "master" stored proc that was kicked off nightly by scheduled job.
The existing documentation consisted of a single word document, about three pages long, describing how to set up the application... on the Sql Server 6 server it had been originally created on two generations ago. -
Just wasted two hours finding out why one of our clients rest API is not working. Apparently it needs a referer header for no good reason and this is no where to be found in the documentation...
It is great that you even have documentation, but please include all basic details!! -
our office software has the shittiest documentation. no problem! i love to browse all the subfolders to find where to place a serial letter template! why would someone want to do this in the first place?
if someone working in the german medical field: i can not recommend eva/viva for some other reasons as well. -
Is there anyone out there who knows opennms? I got assigned to "improve" the nms diagnostics page (graphs are drawn and shit) but I can't find any dissent documentation. My task has even been changed to "if you solve the problem, write down a documentation on how you did it"
So yeah... Feeling lost.. Not even a SO thread to help me 😳😖1 -
Joined a new team at work hoping to learn something new. Was told by the team lead that they will be starting development on a new project that I was interested in.
Guess what it was all a fucking lie. I'm assigned a task to create documentation for some legacy java shitcode without any fucking comments.
Fine I get it, they say it's required going down the road of the new project as it will work alongside the old application. But the code is so fucking bad. For starters
-The db host and credentials are hard-coded in a million places
-it stores user credentials in plain text
-its creating files in the fucking filesystem to store things instead of storing it in the db
-each functions ranges from 100 to 8000 lines of code
Who even codes like this 🤯
And I can't fix these issues. All I need to do is document every function and class and package. Fine. Fuck this shit -
if you write awesome code that's undocumented nobody will ever use it, or why I use external open source libraries over internal ones
-
To most non-dev people, being hit with error after error when fixing one small problem out of a much bigger collection of problems would probably be infuriating.
To me, it's a huge loop of:
for(var failsAtLine = 1; failsAtLine < lines.length; failsAtLine++;) {
changeSomething();
runTest();
readErrors();
cry();
comtemplateMeaningOfLife();
}
openChampagne();
Would help if deployer.org had better documentation and bigger support community.
-
Isn't it great when you get urgent tasks, but the documentation required for it can't be found or doesn't even exist, and the devs that worked on the project before are no longer in the company? And then the producer gives you some document that is completely unrelated?
-
It should be illegal to have a 12 year old documentation for an c++ API... even though it's my fault I suck at c++ ...
Bluesoleil , the only Bluetooth you are giving me is a rather unpleasant story.. -
Really need to make it a habit to read every single piece of documentation and included read me file for a plugin and framework that I'm using even if they essentially say the exact same thing...wasted so much time just to find out I literally needed 1 line of js instead of all kinds of custom code -_-
-
!rant
So, I wanted a little suggestion here.
I'm currently interning at a startup and currently we document our build procedures by creating .docx files containing the steps. But docx is a pain in the ass. I'd rather prefer markdown for documentation.
Are there any better tools for documenting? What do you guys use?
We're using Jira for project management bdw.1 -
Learning a piece of software from an external supplier. The manual is thick like the bible. The examples fail without explanation. Trying to contact support just leads you down an endless trail of support articles. Damn right I get frustrated and bored. Can you blaim me for rather hanging around on devRant than desperately trying to work around problems in someone else's system/documentation? Yeah, I have to pull my shit together, but they have to pull theirs first.
-
Why does the biggest mobile money payment system in our country have such crappy documentation! Arghh
And they tell us to read the DOCUMENTATION it has all the answers -
looking for suggestions for a self hosted CMS. I tried Ghost, and it looks real nice, but there's no option to have just 1 section be private, you can only make the whole thing private. I tried Drupal but honestly it's just way too complicated for what I need, and doesn't look very aesthetically pleasing.
basically, here's the features I'm looking for:
- ability to set privacy/access control on a per-page or per-section basis
- Markdown for content editing
- ability to use regular HTML when needed
- ability to upload content via an API (so that I can publish documentation via my gitlab CI)4 -
Is there any good freeware to make an IT-Documentation from every Device witch is connected to the Companies network?4
-
Fuck you, BouncyCastle. I really like you but the way you have documentation. It's annoying. Nice name. Cool project.
Here, I'm write Java Docs for JUnit tests! For every damn test case!
So damn less documentation even SO said mind your own business! It's been more than 15 hrs. Not a single reply! I died a little today. They have examples but they are not really "examples". No passion at all for documentation!
You should watch and learn from AssertJ docs. OMFG @joel-costoglia sets standards for code style and docs before pull requests. The examples are LOTR themed for god's sake. I'm not asking for fluent API. I just want docs. What class does what. A simple program structure required.
Dyn4j, deeplearning4J have wonderful docs. Why not BouncyCastle?!!!!!
-
Autodesk's documentation in general must be the worst documentation ever made!
Im shocked that a company creating a HELP TOOL wont even provide structured and decent documentation! -
Very reassuring when your payment gateways XML examples have invalid markup.
I asked for XSD's and even they are invalid (containing missing type references) -
Code examples with dozen of lines in the project documentation (docx) are screenshots... lazy to format or to prevent simple copy and paste? That's the question.
-
My testing team just asked me for documentation for a screen a webapp. I had to make a small change in it which was regex and had to allow another char, which was quick fix. The code has single letter variables and huge java code in jsps,
How can i even find a documentation for it. -
Hey! It's been a while that I've been searching about projects documentation in order to develop a template for the company's projects.
My goal at the moment is technical documentation, like getting started (for new developers), the project's dependencies, conventions, etc.
Does anyone have suggestions of articles, books, or any resources about that topic?
Edit: I'm planning to build this template, discuss it with the seniors and then present it to the managers.1
Top Tags
Weekly Rant
View
Same lol