|
Wheany posted:or they document poo poo only superficially, so it looks like good documentation at first yep, and since there are no access modifiers there's a lot of guessing about what's meant to be a public api and what's not.
|
#
?
Apr 8, 2016 14:01
|
|
|
|
| # ? May 24, 2024 22:08 |
|
|
good documentation is hard
|
|
#
?
Apr 8, 2016 14:09
|
|
|
Blinkz0rz posted:good documentation is hard no it's not. it's just boring to write, so nobody does it.
|
|
#
?
Apr 8, 2016 14:35
|
|
|
decent documentation is merely boring, but it's easy to dump a bunch of time and effort into documentation and still not end up with something good.
|
|
#
?
Apr 8, 2016 14:40
|
|
|
i used to write docs, but no one would know where to find them because reasons. then i'd show them where they were, and the response was always "can't you just tell me what i need to know?", so now i don't write docs any more.
|
|
#
?
Apr 8, 2016 14:50
|
|
|
legit good documentation is difficult. acceptable or tolerable or good enough documentation is pretty doable
|
|
#
?
Apr 8, 2016 15:04
|
|
|
i write documentation for myself and stick it in the program's confluence, which i am the only user of. any time someone asks me something thats probably documented i just say "did you check confluence" and then they bluster a bunch about how theyre too good for using useful tools
|
|
#
?
Apr 8, 2016 15:05
|
|
|
Bloody posted:legit good documentation is difficult. acceptable or tolerable or good enough documentation is pretty doable I agree with this post. Acceptable/Tolerable is easy; if you're lucky enough your users are going to dive in the source and be ready to do work to get the information they need. If you have decent docs, the users can find everything in there, but they have to read through stuff. But that's just decent. There's a really difficult threshold to cross where you have to conciliate brevity and completeness or just find your place on a spectrum between two extremes, where you get comments like: - I want simple examples / I want examples that are not just trivial stuff - the content is too generic for me to imagine using it / the content is too specific for me to figure out how to apply it to my problem - I don't feel like I have the right background for this / there's too much time spent showing the very basics - the tone is too dry / the text feels patronizing - there's too much code / not enough code being shown - the documentation is too long / the documentation does not have enough details and so on. Finding how to properly balance that is, in my experience, very hard, and I'm still not sure there's any solution other than "define your target audience, pick one way to do it and stick with it; someone else will write docs for the other audiences". This creates hit-and-miss approaches, but trying to do all of it at once is a very tricky affair.
|
|
#
?
Apr 8, 2016 15:27
|
|
|
good docs for users is hard as hell because they're always dumber than you think. good docs for developers is more probable b/c when developers are dumb you can fire them.
|
|
#
?
Apr 8, 2016 15:29
|
|
|
lol if you think we've ever fired an employee.
|
|
#
?
Apr 8, 2016 15:30
|
|
|
for the rare times i write docs I like to have high level summaries of workflows and processing concepts w/ links into the implementation details.
|
|
#
?
Apr 8, 2016 15:39
|
|
|
Shaggar posted:good docs for users is hard as hell because they're always dumber than you think. good docs for developers is more probable b/c when developers are dumb you can fire them. devs are fairly lovely for multiple kinds of docs. They do that "doctor killer" thing where they just assume they know a bunch of poo poo, skip over basics, then come complaining that stuff is not working properly when they crash and burn. Then you have to point to them that if they read things in the order they're supposed to read it, they wouldn't have the problem. The more you reader knows, the harder it is to railroad them and build up knowledge of your system/tool/whatever in an axiomatic manner, and the more they'll tend to skip around in frustration and take 3 times as long to learn as anybody else because they keep trying to jump ahead when they shouldn't. So you have to try to coax them into doing things in order. Start poo poo with a list of steps they need to take or things they should see, and maybe tell them when they can start skipping around. If you show that early, they'll internalize the idea they shouldn't skip around better, but it's not always easy.
|
|
#
?
Apr 8, 2016 15:39
|
|
|
I find its a good idea to write your dev docs as if your target audience doesn't work for your company. the summary info at the start should additionally be written as if you're audience is a sales or account person.
|
|
#
?
Apr 8, 2016 15:45
|
|
|
MononcQc posted:I agree with this post. Acceptable/Tolerable is easy; if you're lucky enough your users are going to dive in the source and be ready to do work to get the information they need. If you have decent docs, the users can find everything in there, but they have to read through stuff. But that's just decent. communication usually fails, except by accident
|
|
#
?
Apr 8, 2016 15:45
|
|
|
what's the goon verdict on doc comments? i pushed pretty hard for them as the only kind of docs our devs might actually update, got overruled and we now have confluence docs that are far enough out of date to be more dangerous than useful.
|
|
#
?
Apr 8, 2016 16:19
|
|
|
before i was a programmer i was a technical writer. mediocre documentation is easy but your users will hate you. good documentation is 80 hour weeks forever and your users will have basically no reaction to it whatsoever. there is no in between. being the documentation person sucks, i don't blame people for not bothering if they can get away with it.
|
|
#
?
Apr 8, 2016 16:21
|
|
|
LeftistMuslimObama posted:before i was a programmer i was a technical writer. 
|
|
#
?
Apr 8, 2016 16:21
|
|
|
MononcQc posted:The more you reader knows, the harder it is to railroad them and build up knowledge of your system/tool/whatever in an axiomatic manner, and the more they'll tend to skip around in frustration and take 3 times as long to learn as anybody else because they keep trying to jump ahead when they shouldn't. Not really a problem I guess for the smarter people out there.
|
|
#
?
Apr 8, 2016 17:11
|
|
|
ill just google this nevermind q was for map which maintains key order
Share Bear fucked around with this message at 17:33 on Apr 8, 2016 |
|
#
?
Apr 8, 2016 17:28
|
|
|
LinkedHashMap
|
|
#
?
Apr 8, 2016 17:30
|
|
|
more like dICK posted:LinkedHashMap word thanks
|
|
#
?
Apr 8, 2016 17:32
|
|
|
MononcQc posted:They do that "doctor killer" thing Is that the wrong URL? Or am I missing something (  i skimmed the page)
|
|
#
?
Apr 8, 2016 18:38
|
|
|
HappyHippo posted:Is that the wrong URL? Or am I missing something ( quote:The V-tail design gained a reputation as the "forked-tail doctor killer",[10] due to crashes by overconfident amateur pilots with high-level skills outside aviation, [...] "Doctor killer" has sometimes been used to describe the conventional-tailed version as well.
|
|
#
?
Apr 8, 2016 18:44
|
|
|
Also this owns http://classicprogrammerpaintings.tumblr.com/
|
|
#
?
Apr 8, 2016 18:45
|
|
|
So this just came up as a bug and now I'm wondering about best practices. There was a thing being cast to an int that was raising an exception that has code catch and handle it silently and with nothing logged (that's fine, right?  )Changing the cast to Convert.ToInt32() fixed it, but now I wonder if I should just do this instead of casting for everything. e: grammar HoboMan fucked around with this message at 21:33 on Apr 8, 2016 |
|
#
?
Apr 8, 2016 19:31
|
|
|
HoboMan posted:So this just came up as a bug and now I'm wondering about best practices. that depends on the language and the use case. if youre going to continue using it as an int/store it in an int variable then yeah using convert is sop. if its, like, a pointer then theres probably a lot of crazy edge cases to think about that hackbunny is way more qualified to tell you about than i am.
|
|
#
?
Apr 8, 2016 20:43
|
|
|
MononcQc posted:Also this owns http://classicprogrammerpaintings.tumblr.com/
|
|
#
?
Apr 8, 2016 20:45
|
|
|
MononcQc posted:Also this owns http://classicprogrammerpaintings.tumblr.com/
|
|
#
?
Apr 8, 2016 21:33
|
|
|
MononcQc posted:Also this owns http://classicprogrammerpaintings.tumblr.com/
|
|
#
?
Apr 8, 2016 22:54
|
|
|
MononcQc posted:Also this owns http://classicprogrammerpaintings.tumblr.com/ https://en.m.wikipedia.org/wiki/Rep...cks_-_Yorck.jpg needs one
|
|
#
?
Apr 8, 2016 23:01
|
|
|
reviewing a legacy codebase the other team will take ownership of
|
|
#
?
Apr 8, 2016 23:13
|
|
|
"Coding Team Replying to Latest Feature Requests"
|
|
#
?
Apr 8, 2016 23:13
|
|
|
I would read a thread where we just do this all day.
|
|
#
?
Apr 8, 2016 23:33
|
|
|
"Offshore team responding to request from HQ for more documentation"
|
|
#
?
Apr 8, 2016 23:33
|
|
|
"The sales team came up with a new way to pitch the product which is impossible in reality"
|
|
#
?
Apr 8, 2016 23:35
|
|
|
MononcQc posted:I would read a thread where we just do this all day. https://forums.somethingawful.com/showthread.php?threadid=3771539
|
|
#
?
Apr 9, 2016 00:35
|
|
|
CPColin posted:"Offshore team responding to request from HQ for more documentation" I like this one
|
|
#
?
Apr 9, 2016 00:42
|
|
|
CPColin posted:"Offshore team responding to request from HQ for more documentation"
|
|
#
?
Apr 9, 2016 08:42
|
|
|
our big documentation challenge is that our product is really big and while it's pretty easy to find something going wrong (thanks stack trace explorer), it's hard to figure out what's going on when things are working right unless you've lived in that part of the code for a while. there's no documentation of the DB schema anywhere that I can find for instance, and there's very high level architectural overviews but nothing really at a 'if i do x, how do i expect it to go through various services'
|
|
#
?
Apr 9, 2016 15:13
|
|
|
|
| # ? May 24, 2024 22:08 |
|
|
uncurable mlady posted:our big documentation challenge is that our product is really big and while it's pretty easy to find something going wrong (thanks stack trace explorer), it's hard to figure out what's going on when things are working right unless you've lived in that part of the code for a while. there's no documentation of the DB schema anywhere that I can find for instance, and there's very high level architectural overviews but nothing really at a 'if i do x, how do i expect it to go through various services' this sounds more like the challenges of not having documentation than the challenges of writing documentation.
|
|
#
?
Apr 9, 2016 15:25
|
|
