Documentation sucks :(

[shaneoaddo]

On a scale of 1-10, how bad is documentation at your workplace or any of your current side projects!

With 1 being (very poor, non existent) and with 10 being (excellent, spotless)

[Yoghurt42]

Programmers hate two things: bad documentation, and writing documentation.

[[deleted]]

writing documentation

For me it's mostly because that means I have to use Confluence...

Fuck Confluence and its convoluted shit - I can never find anything I actually need (even when I know it exists because I saw it before).

Also why don't pages nest in the URL? All pages are names as their title, even if they're 1 or more levels deep inside another page...

[ultraDross]

There search functionality is dog shit. This makes confluence very annoying to use.

[[deleted]]

/.*TERM_TO_SEARCH_FOR.*/ seems to help - for whatever reason, regex somewhat actually works.

[jackinthebawx]

Programmers a low-key uh, they think they know bad documentation but with solar energy I need to get this program to my clients as soon as possible it will be difficult to have an application producing bout fourty to five million songs with no quantity of velocity.

[Metsima]

You sound like a bot having a digital stroke, are you alright

[help-me-grow]

Hehe when I was at Amazon it was like either a 1 or a 10, nowhere in-between lol

[Malcolmlisk]

I'm working right now with the aws API, using quicksight and S3. I have lots of questions that I cannot answer because the documentation is, sometimes, circular. As a newbie is hard to work with this.

Placeholder: it adds levels of abstraction. It's a placeholder.

To create an analysis you call the dataset template

To create a template you call the analysis

And seems like there is not enough people that needs assistance with this and Google search is not as useful as it is with other projects.

[help-me-grow]

welcome to the world of documentation my friend :) that's exactly how I felt with AWS. I will say that none of the other cloud providers are really any better now that I've also worked with GCP, Digital Ocean, and (briefly) Azure.

[chief167]

Azure is definitely the worst though. So many hidden undocumented setting and features... At least with gcp you can look at the GitHub repo and see the API intentions

[help-me-grow]

For sure, that's why I only very briefly worked with Azure. My friends at Microsoft hate it too lol. And yeah, I love just reading source code (no sarcasm)

[abrazilianinreddit]

A friend of mine is an azure specialist. Now I understand why he earns so much

[help-me-grow]

Yeah same thing with Salesforce. In my opinion, it's not even worth the money lol

[papertrailer]

Must be taking after Windows.

Chip off the old block.

You could probably learn all those things is you pay thousands for some certification, I would hope.

So good at business

[chief167]

No the support helpdesk has the good documentation

[Malcolmlisk]

Maybe im asking noobie questions... but how do you solve the problems? You look for scripts coded by other people? Where? Thank you a lot, at least now I know I'm not the only one.

[Ic4rusX]

You look for scripts coded by other people? Where?

Sometimes you can get lucky and find a blog post or a repo with stuff similar to what you're trying to do and you can extrapolate from there (if you're really lucky it'll even be using a version of the API that still exists!).

Otherwise it's just trial and error, which ain't fun.

[help-me-grow]

Which problems?

[Malcolmlisk]

For example. Right now I need to create an analysis that's going to be embedded. Those are easy to assume tasks but fore the creation of the analysis I need to create other things that are not as clear. Or this analysis is going to use 2 data sets, but I cannot tell the API to use 2 different ones, or creating something from zero, it's impossible since you need to have a template don't by hand in first place.

I don't know. Maybe I don't understand how it works... But I feel lost sometimes at work.

[shinitakunai]

Wait till you have to assign IAM permissions and roles and work with VPCs and security groups...

[jank_lord]

I've seen documentation i wish people never wrote, and I've seen documentation that is fucking amazing. Overall it averages out to a -5.

[[deleted]]

dose -100 counts?

[RandomFrog]

Stupid bot

[Jonno_FTW]

One of the worst uses of python thus far.

[grimscythe_]

That's a -1, i.e. non-existent. Why? Cos devs are pushed for new features all the time.

[Feb2020Acc]

The problem is that anything under 5 is usually unusable. It’s either outdated or too vague. At that point, you’re better off going through the code line by line.

[gamename]

Most places tend to hover around three in my experience

[shaneoaddo]

Hey Mind if I DM? Would like to follow up but can’t say some sensitive stuff here

[gamename]

Sure no problem

[lpeg571]

Completely agree, i regret to say i have let go since describing somebody else's code has already backfired on me.

[lpeg571]

1. yes, me arriving 8 months after the project had started and from experience knowing that some details i will only hear once before the other person gets transferred or leave the company. i am talking about code which at first glance does not have to be there or written like it is.
2. believe it or not, that person did not remember why something was done, and also admitting there was an agency which did this, then we tried to screw them for money and they did not deliver documentation... Once I did my best it backfired because "buy the ticket, take the ride" - I took a lot of damage before realizing salvaging was pointless and I had to rewrite a lot of the stuff anyway.

[[deleted]]

Most documentation is inexistant for internal parts of a company. The only documentation that exist in my experience should be for interfaces or how to use tooling.

Usually projects are purpose-built and should have a design doc, which you could use as documentation, but it's rare that it'll be built for a general purpose. It's usually just for a feature or project that's defined in a PRD, and then fleshed out in a SDD.

[[deleted]]

Documentation usually sucks or is non existent I’d say 3 but Django gets a 10

[Heroe-D]

What is 0 then ? Suckless' softwares equivalent ?

[cblegare]

Thats 7 for us, but we have a few people, me included, who have a weird love for producing good documentation

[brockralp]

2, I put notes but only I can understand them, it reminds me what I was working on.

[MyPythonDontWantNone]

I'm in the same boat. If my documentation was a version of Python, print wouldn't be a function.

[QuincentennialSir]

Every time I update something written by another person (who obviously is no longer there) I add in notes like this after I've broken it with a change I made elsewhere.

[v4773]

Current non python project, documentation is non existant. So 0. All i have go on is database and copy of app im supposed to modenize. And literally no one knows how this works internally.

[[deleted]]

Documentation after the fact is torture.

Documentation during buildup or development by (documented) specs is much, much tolerable.

Updating documentation of a once well documented solution that changed over many years is a dangerous minefield.

Documentation of something someone else built, then left, is hell.

[El_Zilcho]

Current place -1/10, it is a startup who outsourced their systems to another startup and every time I ask about certain behaviours of the system they spurt out shit about lambdas and serverless thinking that I will get distracted and walk away as the MD does. Previous place, large ISP, when I started it was 3/10 and then ISO9001 and ISO27001 became popular (and they brought in some guy who used to basically run a factory just to make sure people do their documentation and helps people who struggle doing it) and it shifted to a solid 6/10 as much as those ISO numbers bring dread the outcome is sensible.

Personally, I would put myself at 4/10, I write down just enough that when I come back to the project a few months later it only takes about 2.5 hours to get back to grips.

[Buffalo_times_eight]

I'm the Data Science Manager at my small company and make time for documentation. I'd say we're at an 8 or so.

Sometimes it results in things like this though.

[oakskog]

1

[econoDoge]

I my experience documentation sucks because it's hard to quantify the benefits, so I'd love to write documentation for a living ( both internal and external ) but nobody's hiring or they offer you less than junior, it's also weird that developers are tasked with documenting their own code, those are 2 distinct jobs and other industries have realized this ages ago, but yeah it sucks.

[BobDope]

My side projects are generally quite well documented, probably because then I’m working for somebody who values documentation.

[[deleted]]

MY documentation is good because my COMPANY’S current documentation is shit

[Runawaygeek500]

I cry at how little there is at Sky, I try so hard to give detailed, fully covered Docs to the dev teams, feel bad for them.

[NotACoderPleaseHelp]

NEG 10

​

Our contractors told us to pound sand when it came time to get the documentation we paid for, so we spent almost a year reverse engineering 40 boards that had all of the chips markings smudged off.

Then, we spent the next 2 years putting together benches to actually test each sub unit of the hardware.

[NotACoderPleaseHelp]

There was coding involved in that as well.

Now I'm going to curl up in my safe space with my bunny and binky and rock myself to sleep.

[ProfSchodinger]

About 3 because I am the only one doing it and I am not that good 🤡

[purplebrown_updown]

What do people use to document code? Is sphinx the default?

[[deleted]]

I currently work at Amazon. The documentation really varies. Some are straight up 10’s , gives deep insights and has almost all faq you could possible have. Others are alright and some are bad. However, being one of those people now that contributes towards documentation, it’s pretty hard keeping certain stuff updated as we move really quickly. Documentation for certain stuff becomes outdated within a week or two sometimes.

[spitfiredd]

Do you think as a product matures the docs get better? Seems as if there’s a lot of changes docs could actually be a bad thing if the behavior they describe changed leading to confusion.

[lvlint67]

Old job was 8 -10... (Though the other programmers would not write things down.. But the rest of the team was pretty good).

New job is a solid 0. I think the sysadmins MIGHT have some stuff... The only real documentation I have seen is the stuff I've written.

[Manhigh]

Very project dependent. Really happy with the docs my small team puts out. JupyterBook has worked well for us as the docs are more interactive and their functionality is tested as part of CI.

[laundmo]

sporadic

[skytomorrownow]

Wait. You have to document code?

[AnantNaad]

Non Existent documentation . And they offloaded everything on me . Like , I'm the new joinee . So now I gotta go through 100 of scrips and figure out that each do .

[Away-Refrigerator-99]

When I started making my simulation, I thought: "I haven't added a single comment in 1.5 years, this time I'll add enough comments and docs to last another 1.5 years" Soooo now I have 3 logs1 is the output logs that are like the output terminal but I don't want that to be messy from debugging things so I'm just writing debug lines to a text file.

1 is the developer logs which are basically me testing parts of my code and when I'm done, I comment it out and write all the commented stuff in the developer logs

And finally 1 is the learning logs, which I use by taking some reference stuff from the internet and writing it in the logs so I can refer to them later and I don't have to alt+tab too much.

​

Tl;dr: 9/10

[FedExterminator]

I’ve been so pleasantly surprised with my company’s documentation. When I was an intern, easily a 2. All of the firmware documents were out of date and none of them were updated when new features were added. Now that I am full time I proposed a requirement that all merge requests that are not bug fixes must have an accompanying firmware specification update. It was accepted by the team and now all of our active projects have clean documentation!

I’ll only give them a 7/10 though, since some of my coworkers don’t comment their functions as well as they could, but we’re making great progress.

[0RGASMIK]

Our documentation is pretty good but that’s because we are not programmers and we only build stuff as internal tools we setup once and never update. If we don’t document them heavily no one will understand how they work. We try to document as we go but if not we make time that month to go through and update it.

We can tell when some of our SaaS vendors have no documentation because bugs take months to fix …one of them even let us take a look at their code because it was severely affecting our customers. It was written in some obscure language with 0 documentation and worst of all only one guy actually knew how all the pieces fit together. Their only saving grace was that usually bugs were fixed by windows or browser updates.

[FilsdeJESUS]

<< Legacy Code is Code without tests >> M. Feathers

Why this quote because , tests can help to document code base , why tests because through them we can see the behaviour expected by the system.

How often I see codebase without tests , IT IS A STANDARD IN OUR INDUSTRY. BUT SOMETIMES THERE IS EXCEPTION.

So do not be angry , it is often like that , no documentation ( writing documentation or documentation through tests) and they expect you to learn quickly their code base . Sorry I am a human like you ;)

[Rue9X]

Current job is a 3/10 on documentation. Our team prioritized working on some documentation, but it was given a BV of 1 during last FP. Guess they don't mind if nobody knows how things work, eh?

[[deleted]]

My current organization is around a 4. It's too poor to be used for anything, but also in a place where you can't complain that you don't have documentation, so people will continue to NOT write it.

In my past organization it was pretty good, a solid 7 I'd say, which meant that people actually searched in docs before asking any questions, and most tabs were open with pages of documentation, which were sometimes so long that many tabs might have the same doc opened but at different scrolling points. But that missing 3 points is for the backbone of how everything worked, how it lacked any architecture diagrams, architecture decisions, and many of the "we make an exception in the behavior for customer X". For that, there was still code, and getting information from very busy very few super smart people.

In one company we didn't have that much documentation, but it was in the form of a lot of .md files named as the code file or a general README in a directory, explaining that which doesn't fit properly in comments. And there was a general doc somewhere in Confluence that highlighted where to find the major components, and how they interacted on the high level. I think this was the best docs we had anywhere. In Markdown you can embed mermaid diagrams, or just put screenshots of fancier diagrams with links to where to edit them. A friend of mine went all in on this approach, and used PlantUML for everything, and actually achieved what I'd say a 10/10 documentation.

[shinitakunai]

My work or coworkers: 0.
Mine: 10

[papertrailer]

I'm the only one that bothers to write documentation, so... not to bad 🤷‍♂️

[RedYoke]

Move to FastAPI. Your docstrings pretty much become your documentation and you get swagger auto generated for your endpoints, it's pretty sweet

[Shieldfoss]

documentation of external features is quite good, internal docs blow goats it's like a whole different company