T O P

Who can relate?

Who can relate?

Amazed_Alloy

Qualifications for documentation to be well written: 1. Has examples 2. Doesn't use a load of technical terms that could be swapped for simpler ones


ravepeacefully

> Doesn’t use a load of technical terms that could be swapped for simpler ones Arbitrarily complicated terms in documentation are so frustrating. We get it you’re smart, but the goal is to simplify, I’m a programmer not a contextual linguist.


Kenkron

It's so common too. Average? Sad drake. Normalized sum of equally weighted values? Glad drake.


kn33

If they want to be specific they should use "mean", not whatever monstrosity you wrote. But they don't...


lead999x

But then they'd have to specify arithmetic mean or geometric mean.


TheXGood

I mean, saying arithmetic mean is probably the best compromise. Worst case: skim the Wikipedia article or the Google definition


kiwidog8

Here try this, I learned it on another subreddit ✋ Average 👉 Normalized sum of equally weighted values


chokoladeibrunst

Ordinary image-based memes? Sad drake. Text-based memes? Glad drake.


T_D_K

Average is ambiguous. Mean (or even better, arithmetic mean) is what I want to see, so I know what I'm getting. Documentation is the technical description, it deserves precise language.


xxkmatiasxx

it should simply describe the code at the same of documenting what it does


GuzioMG

Someone give this man an award, he's speaking pure facts. EDIT: fixed my broken grammar.


Kenkron

Here is the perfect documentation: `\frac{1}{n}\sum_{i=0}^{i=n}a_i` TBH, I have no idea if you're being sarcastic or not.


PM_ME_C_CODE

I had a good boss once explain the following to me: Good documentation *explains* jargon, but tries really hard to not use it. ​ We were building API backends that presented financial information for other teams across our company to consume when creating their internal reporting software. So they had to be able to get up and running with only our documentation since we didn't have any budget to hire someone to hold their hands for them.


Blue_Moon_Lake

My favorite thing to have in documentation is for jargon to be like this jargon


GuzioMG

I'd also add "properly organized", too. I hate it when the devs just slap an usage example for each method/function on their GitHub readme.md and call it a day. There's a Wiki section, for God's sake! Just use it, it's one click away.


bezz

Examples are so helpful to me


Sarcastinator

Yeah examples are great. But I'd rather have documentation without examples than documentation that is nothing but examples. Today I was struggling with an API that was documented only by an example program. One of the API calls didn't work because of a precondition that the example didn't specify or make clear in any way.


pseudomota

Wish I could upvote this a billion times. Examples are very helpful but providing *only* examples without any actual documentation or explanation is truly horrible


iamsooldithurts

If they can’t write good examples that adequately explain all preconditions, what makes you think they can better explain it using words? Some people learn better through examples, some don’t. Good documentation provides both, with all of the information necessary to actually learn the thing successfully. The rest is up to the learner. I once struggled through learning a new project/library for six months because they didn’t have examples and the written docs were bad. I finally figured it out my struggling through writing code, downloading their source code so I could step through it, and asking everyone I knew for sample code that worked in their projects. Edit: the worst part of it was they build their own ApplicationContext structure that was tightly based off of Spring’s ApplicationContext but only half of the actual features. That took four months to figure out, after that everything else started to fall into place. The only thing that sucked worse than their code was their documentation.


Sarcastinator

The application required that you copied a executable file to the binary folder of your application or the init calls would just return failure.


riickdiickulous

When I started writing python libraries for my company I spent a solid week researching and learning proper documentation. The people using the libraries had 0 coding experience so knew it had to be top notch documentation. It was a pretty hard process but my documentation and code writing style is so much better because of it.


JhelmerF

Can you recommend any resources for this? I would love to get better at documentation.


riickdiickulous

The article from Real Python “Documenting Python Code: A Complete Guide” has a ton of resources I learned from. And the PyCon 2017 talk by Daniele Procida was super useful.


CinderBlock33

I got irrationally angry from the memories this comment evoked. I hate it so much when technical documentation uses buzzwords/marketing words. Like I don't CARE. just tell me how to do the thing in the simplest terms possible.


Tristan401

Or when they use vague industry-specific words


charomega

1. Has real life examples FTFY


DazzlingAlbatross

I'd say that eliminates most `man` pages.


farva_litter_cola

Simple examples. Most of them have complicated examples that require additional knowledge to get that trash to work.


c1e2477816dee6b5c882

And examples that span from simple to more complex with a bunch of best practices provided in the example with comments and rationale as to why they ARE the best practices.


PapoochCZ

Why is it always that the documentation of the new framework looks beautiful and complete at the first glance, not like the disaster that is the one for that framework you are using now? Then you start actually using it and learn that it's the same crap as the previous one and only the most basic use cases are covered :(


kor_the_fiend

Well, when you are first starting out with something, you are probably only interested in the basics. Once you get beyond surface level, that's when the holes in the documentation become apparent.


AzuxirenLeadGuy

The problem is that well written documentation are not very common


freefolkonly

Exactly, looking at you Parse. Even your name makes it hard to google anything about you.


Bimpnottin

I’m in bioinformatics and use a tool called ‘sniffles’. It’s impossible to google and I once made the mistake to google ‘man sniffles’. I swear they do it on purpose


Diptam

Don't you know it! I'm not sure why, but bioinformaticians really like their acronyms as well as naming them after normal english words. blast, glimmer, trinity, lace, meme (this one is weird, because the word "meme" was coined by the biologist Richard Dawkins, but has a very different connotation these days), galaxy, emboss, harvest, mega. Just to name a few of the easier to find (because of their popularity). And that's not including any puns.


caskey

Interestingly this is one of those areas where Google search history helps you. A search for "sniffles" by someone who tends to search for bioinformatics topics will get a different sorting of the results than someone who has children and searches for stuff related to childcare. Despite everyone's fear of big evil tech being out to ruin our lives (and there are unintended consequences), most of it is designed to work for us.


yooman

Well, it's designed to collect and sell our data, you're just describing the side benefits they give us so we'll let them get away with it.


phaelox

And while there may be positive use cases for filter bubbles ("personalized" search/feeds), they are detrimental to our society as a whole. Filter bubbles have literally contributed to genocide (for example in Myanmar against the Rohingya, Facebook played a major role) and terrorism (right-wing nut jobs plotting coups, bombs and kidnappings of officials), as well as large scale death (antivaxxers have caused many to die by believing lies, not just antivaxxers themselves).


Mefistofeles1

Though lets make it clear that the solution to that problem is NOT to give big tech complete and absolute control over the flow of information and the power to censor whoever they dont like. That just changes a bubble for another one but this one sponsored by corporate. I dont know what the solution is, though enforcing freedom of speech on social media is obviously needed. Maybe decentralized networks? Or just nuke social media lmao


ispendmoremoney

reddit is social media. we all hang out in our corners of the internet. some people are probably getting radicalized right now


CptGia

The main programming language at CERN is called ROOT. It something is not in the internal wiki, good luck finding anything related on Google...


augugusto

If you ever forget how to use the tail command, just google man tail


notagoodboye

There is a common automation framework called “Chef” and they name all their tools after memes or things a chef would use. Total nightmare.


GisterMizard

Just add "ansible" to your searches. Then you'll get all of the stackoverflow questions where somebody gets in a fight about which is better!


ILikeLenexa

Can anyone remind me the syntax for "c strings"? What's the manual page for finger say?


M00ny0z

Wow. My next bucket list item is to write a good library with gay innuedos to force devs to accidentally search gay porn. Thank you.


gregorydgraham

That reminds me of back in the day when I was trying to find more music by The The


sassy4096

Worst band name ever.


King_Bonio

There's The Band as well, almost as bad


magicmouse99

What band?


King_Bonio

The Who? No, The Band.


Zerafiall

The babe?


UltraCarnivore

The Unforgiven


TwatsThat

What babe?


Dantheheckinman

The babe with the power!


laika404

The Who's on first, The Band is on second


ChefExcellence

'!!!' has to be the worst, I reckon.


ShipWithoutAStorm

A while back I discovered an artist on Spotify named ⣎⡇ꉺლ༽இ•̛)ྀ◞ ༎ຶ ༽ৣৢ؞ৢ؞ؖ ꉺლ It can be a little tricky to find that music again.


TTrui

It is an alias of Four Tet, so you can find him easier that way :)


CAT5AW

There is also an artist that both its name and album name were made entirely of dots and dashes, morse code style but not quite. ・ ・-・ ・- ・・・ ・ -・・ is the name. https://open.spotify.com/artist/0EUOiLsLpv9g7H9YCzUnBS spotify link. Some electronic music Edit: this morse stands for ERASED


King_Bonio

Aren't they pronounced "chit chit chit" or something?


gregorydgraham

Definitely the worst sentence ending


TheRealPitabred

Put quotes around words you want to keep together in Google searches: https://www.google.com/search?q=%22the+the%22+band


gregorydgraham

Google find The The easily these days, apparently they’re very hip and clever


TheRealPitabred

Hah. Sure, but the point still stands when trying to search for things named for common words. Quotes clarify searches.


z-lf

Haha I couldn't even google what it is. Out of curiosity, do you have a link I can use to start?


freefolkonly

I was talking about https://parseplatform.org/


CertifiedCoffeeDrunk

It sounds cool though. Right? Right!? *cries*


Treshle

FUCK tools with super common names 😂


your_thebest

"Parse get vs find" Nope "Parse server get vs find" Nope "parse server get vs find site:github.com" Ok, maybe --"rather than answer your question, could you please explain why you want this?" Nope


GeneralPatten

I wish more libraries/frameworks would include a framework specific “best practices and common standards” in their docs. Make it the first chapter/section. Every framework develops a “culture” within its community of developers. If I’m new to the framework, I’d like to make sure I’m following common practices. If I’m experienced in a framework, I want others coming on board to a project to at least have a basic understanding of expectations.


WiatrowskiBe

Which is why having good, detailed and reliable documentation should be praised.


[deleted]

Good documentations need more recognition for sure.


HobHeartsbane

We need a docember fest in November after the hacktoberfest in October 😅


claryds99

Why not in December?


HobHeartsbane

Why not both?


brimston3-

You're right. Good documentation does take about twice as long to write. Only a little ^/s


waldyrious

Agreed, December makes a lot more sense. Also many people have time off around that date, which may be good for open source contributions ;) I think it should be called Docsember though.


0xcafebo55

Sad but true :-( I remember when I found that Python has a great documentation included in the default install. In Windows you can even have it as a help file (.chm) . Much faster than stack overflow.


wackywavingarmgumby

For smaller things a nice PDF can be better because you can text-search the whole documentation rather than relying on the writer's index.


THANKYOUFORYOURKIND

Well, back in the day (around 2000 or so) you can pack an entire website into a single CHM file, and re-implement it's search function via some script language. Then you basically got a working website expect everything is loaded right after you click. I call it better than just a PDF.


the_captain_cat

Fuck PDF All my homies use Markdown documents


ContainedBlargh

But markdown compiles to PDF real easy


RNGsus_Christ

But why though


brimston3-

- Self contained - relatively immutable when opened by default viewers - native platform support with bookmarking on every desktop/mobile OS install (no extra tools). - standardized TOC generation/view - more reliable support for inline figures - much more reliable support for math/equation formatting - minimal presentation-layer variation (eg, formatting differences between github/bitbucket/gitea). On a personal note, A4 formatted PDF works with a consistent user interface on my phone and tablet and I don't have to fight the reactive implementation on the viewer page. That being said, most of my documentation source is Markdown or markdown embedded in doxygen.


SatoshiL

doesn't chm also allow text-search?


wackywavingarmgumby

Maybe I'm thinking more of the old WinHelp? I've not come across decent provided help files any time recently so I've kind of stopped checking even if I have one.


fmaz008

Especially documentation that confuse being a documentation with a quick start guide that will "guide you" into making a project absolutely nobody wants.


GeneralPatten

The projects are purely for concepts — not some production ready module. If you’re a relatively new programmer, they help provide a foundation for learning more about the framework. If you’re an experienced developer, they provide an easily skimmable reference that you can contrast/compare with other tools you’ve used.


deltamental

Another advantage of those example projects is seeing basic setup of configuration, build tools, boilerplate, and other things like that. Sometimes you need 100 lines of code just to get a minimal working example in a framework. It's way easier to see an example to get a basic "hello world" Django app than try to figure all that out from docs.


AlwaysOneAdvaita

Flutter has good docs


tuks6

Google stuff in general. Firebase/Dart docs are very nice as well.


KeLorean

Microsoft has done well with C# docs


Harmonic_Gear

i find matlab documentation really well written


code-panda

PHP, for all its flaws, also has amazing documentation.


waldyrious

Especially with the integrated user comments, sorted by votes (they used to be there back in the day, not sure if it's still the case). That was like having the docs and StackOverflow in the same page, it was great!


Comakip

Still there! Although a lot of times it's very old. Using a top voted answer from 2009 isn't a good idea.


anakaine

And they serve as worked examples of the documentation just above, which also includes a worked example or two. Between the two its quite easy in most cases to get an idea of how the variation you are trying to implement should/would/could be applied. I'm not a well versed php guy, but I do use it occasionally, and do like the docs.


waldyrious

Qt documentation is also extremely comprehensive and well organized. They even had a wiki that allowed developers to improve the docs directly (not sure if that's still the case though).


mghoffmann_banned

I found the Qt docs to be thorough and searchable which is great, but also very wordy and repetitive which is not. They're like a dictionary when I needed a picture book to get started with the framework.


ArdiMaster

Personally, I find this preferable over needing to piece together information from five different pages.


anakaine

Me too. Give me wordy with a few examples, preferably showing a few ways a method can be applied.


Maleval

Also integrated directly into QtCreator, which makes it super convenient.


VortixTM

Yes this is like saying that a unicorn is better than a horse


Yahlunna

I love Unity doc but for some reason most people hates it. Diferent docs can be good/bad for different kind of people. It does not help that you need to change almost anything the engine has by default to make something decent because of reasons. On the other hand, everyones speak wonders about Rust's "The Book".


Romestus

Unity's normal scripting API docs are wonderful. [Unity's package docs are horrendous.](https://docs.unity3d.com/Packages/[email protected]/manual/index.html)


InvolvingLemons

Rust and Svelte/Sapper/Sveltekit both have an odd situation: it’s almost incestuous how deeply the websites/docs are tied into the ecosystem. Basically every rust library just hosts the documentation alongside the package registry (which is really nice admittedly, cargo and docs.rs are a godsend compared to the fuckery of anything to do with Kubernetes in my experience) and literally every site I’ve ever seen for anything to do with Svelte uses the Sapper default template with basically the only thing changed being the primary color (svelte native swaps orange for blue).


dxpqxb

Last time I've seen really good documentation was in Borland Pascal. Nothing even comes close.


thealliedhacker

(deleted)


caniskipthispartplea

I recently made some very comprehensive documentation regarding the Enterprise software we use, and my co-worker was flabergasted by it, since she mostly just copy pastes screenshots for documentation.


fuzznuggetsFTW

Sometimes you’re lucky to find poorly written, half finished documentation


jp081298

Do you have any examples for documentation that is well written?


Jetpack_Donkey

Old versions of Visual Studio used to come with actual paper books (like 10+ volumes) written by actual technical documentation writers, not software engineers, so they were top notch. You could learn everything you needed from them.


Pocok5

Angular Material and ngrx docs: *laughs in buy the 100$ book instead*


Ooze3d

I wouldn’t say Angular Material is a good example of bad or insufficient documentation. The site is full of examples and the whole API is there. I’m currently working on a project using material and I haven’t had any problem so far.


halffunction

Rust is well written.


Nebuchadnezzer2

I actually remember the professor teaching our Cert III (Digital Media and Tech) covering Documentation and writing it properly. Actually a part of the required coursework. Pity it's evidently not that wide-spread...


GravelWarlock

Or the documentation is about 3 versions old and functions have been depreciated, and there is no example for the new version


macskay

When I started programming I googled everything and landed on Stackoverflow, however nowadays after years of programming I tend to start to hate StackOverflow because almost always the problem I want to solve is slightly different from the one a guy has solved on SO and thus figuring out how to adjust the code to fit my needs almost always takes way longer than diving into the API documentation and coming up with a solution myself. Don't get me wrong, for quick fixes SO is still alright, when it comes to advanced stuff though there is nothing better than a well documented API. SO posts tend to throw you the answer without any explanation. What is that arbitrary number you pass as a parameter? While for the API documentation there is usually no room for interpretation. It literally says what it does and expects.


WiatrowskiBe

SO answers can be a good starting point if you don't know what exactly you need to look for. At least they can send you to a specific part of a framework/library you can then search for whatever answer you need; at best you get a direct reference to docs. Boards are an addition to docs, not a replacement (or at least they should, looking at you NHibernate with absolutely terrible documentation).


Head-System

You know you’re going to have a good time when you start something super technical and the only available libraries have literally zero documentation. Either you have to trial and error your way through hell or write an entire library from scratch, and both are the wrong answer.


Arktuos

Unless your library is closed-source, reading the source is also an option.


deceze

Exactly. Programming is about building your own thing from the parts you're given. The documentation tells you about the available parts. SO and other resources tell you about a particular way to put them together. But the chances that you want to put them together in exactly the same way as somebody else are slim, except for very very common cases and patterns. One of the most important things to learn in programming is to recognise at what level in this hierarchy you are. Do you have a problem with the basic building blocks, or a small assembly of them, or the "final product"; and based on that, where can you expect to find answers to your questions, or does it make sense to ask anyone else at all.


tolndakoti

Nailed it


Tomnnn

ah shit, the stack overflow question I referenced told me to use staples


Ok_Physics_6846

I tried explaining this to my coworkers, and they don’t get it. They ask how I figure stuff out, and I just tell them I looked at the documentation, and the go ‘pshhh, that’s too much to read.’ Meanwhile they’re searching the 4th page of google for some SO answer, and trying to cram it into the rest of their code with no understanding of what it does.


ThellraAK

You try "read the documentation for the specific function"?


WEEEE12345

Well the best SO answers are the well documented ones.


MiniGiantSpaceHams

These days I mostly end up on SO for really obscure things, and often piece an answer together from several posts. Even well written docs don't necessarily cover every weird corner case. Also many docs aren't well written and SO fills the gaps.


HowObvious

> Don't get me wrong, for quick fixes SO is still alright, when it comes to advanced stuff though there is nothing better than a well documented API. God I hate a badly documented API's. I can at least create work arounds or just remake things I have control over. One I'm currently working with the company has repeatedly touted it was great. I've found a bunch of stuff that is contradictory and the whole thing is clearly only intended for the default commands they provide. Meanwhile another tool has a really nice swagger setup and a postman environment download with everything pre populated. Both are tools for Cyber Security which was why I thought the first might be lacking but then I came across the second and realised they are just liars.


IAmNotNathaniel

Nothing like finding an example for *exact thing* you want to do in the doc, and then realizing it's 3 versions out of date and the docs were never updated and the method now doesn't even take that parameter that you needed to use.


Pepito_Pepito

>nothing better than a well documented API They're great... when they exist.


TheSixthDimension

Why not both?


halsalier

How dare you


DrunkOnSchadenfreude

Yeah, one is infinitely more helpful as a quick start when you're looking to learn the basics and get something running and the other is needed to actually get 100% out of it. Both have their time and place and are incredibly useful.


LeoHahn

Nooo you can't be a sensible person it's only 1 or 0


Awkward_Tradition

Quantum powers engaged: now it's 1 and 0


Ross302

Yeah, when I first started programming I found documentation daunting and confusing. Watching people do tutorials where I could see the different pieces working together was way more helpful. Now documentation is often the quick and clean way to answer my question. And when I try to pick up something new, the process repeats somewhat. I feel like OP's meme is kind of reflective of a personal journey many of us can relate to.


Radiant_Bliss

Excuse me sir/madame, I believe the proper phrase is, "porque no los dos?"


r_bfox89

I love arch linux wiki


Laughing_Orange

The best wiki for *any* distro. Just replace pacman with your distributions package manager.


DazzlingAlbatross

People meme on Arch but I swear that wiki has a better written documentation with actual configuration examples and advice on best practices than the programs' original documentation. Unfortunately it seems there's still plenty of programmers and h4xor Linux elitists that believe that user friendliness and documentation has no place in FOSS and everyone should spend hours reading convoluted code instead of having a damn paragraph written on how to use the software. Especially when the program is purely command line and `--help` only returns: --version Print version --help Print this help


ToMorrowsEnd

so many devs too lazy to write docs... instead pay for my udemy course where I recorded the audio from 40 feet away in the bathroom on my phone


squibdib

iOS developer documentation. For a company that prides itself on ease of use, you’d think Apple would do better, but holy fuck is it a mess. React/React Native on the other hand? Pretty straightforward documentation. FB may be destroying civilization with disinformation, but at least they know how to make their technologies easily approachable for developers.


VidE27

What’s a documentation? Is it the same as comments?


cybersteel8

Kinda like git commit messages "code updated" goes a long way


Achaidas

“Please remember to commit in present participle with no reference to future imperfect actions” Like damn, didn’t know I needed to learn Greek grammar rules to say I changed a comment that the end user won’t even see...


DerFzgrld

Cant tell if this is a serious question, so Ill answer it seriously just in case. A documentation is (ideally) a document or collection of documents that contains everything one needs to know about a programming language (in this case, documentations also exist for other things). So it should contain a list of operators, explain the syntax etc. and if its good, it also contains a bunch of small tutorials on how to do some things instead of just mentioning them. So a well written documentation is a great guide to get into a language, is easy to search through for specific problems and features and easy to read. A notable example imho is the Godot documentation. It does a great job at explaining things even at a basic level like vecotors and also has a test project tutorial for starters. A badly written documentation on the other hand, so most, is hard to read, because its badly structured and written to be understood only by experts of that same language, has no useful search, doesnt include a lot of useful explanations and maybe is not even complete.


carbonmeister

Just googled Godot documentation - I have no interest in game design but holy shit, that documentation is cleverly written *and* informative, it makes me wanna go design games.


RedDragonNM

Love the Vue :)


comfort_bot_1962

:D


kpobococ

That is why PHP is still popular. Their docs are godlike.


amrock__

Noobs cannot really learn from documentation. It takes a little knowledge to even understand documentation.


PM_ME_C_CODE

Depends on the docs. PHP's documentation is really, really easy to use, even for a beginner. Learning to read their docs is how I learned how to use docs. And bitch all you want about Java, but their Docs are/were second to none (I cannot speak for the abomination that is Oracle, but back when Sun was still in charge they put a lot of time and effort into their documenations.)


johnfrian

I'm so happy I discovered MDN so I don't have to rely on W3schools. If MDN is the freshly drawn brew, W3schools is the pretty froth on top.


waldyrious

Say whatever you want, but W3Schools was pretty damn useful back in the day. I agree nowadays MDN is better, and I concede that there may have been lots of incorrect stuff in W3Schools (I was never personally bit by that, so I can't say how prevalent the problem is/was), but it sure eas a huge help to most web developers in the early days.


Another_m00

I used MDN for everything, until a few days ago, when I needed to look up webRTC browser API... Uhhh, that topic is so messy that i had to look for another documentation. Then I found a w3scools recommendations which cleared up my view somewhat, but it still refers to some RFC which is plain unreadable...


MuletTheGreat

Why is it either\\or? Typical social media polarising shit. Both man. All these resources have value.


every1listentome

I'm playing both sides, so that I always come out on top!


t00oldforthis

I want to make a snarky "both sides" joke, but you right


Johnny_Gorilla

I kind of agree. The best way to learn any tech stack is to use it. Reading the docs is great but sometimes that’s like reading a dictionary. You don’t need most of it until you hit a very particular use case. Most frameworks/languages come with examples or tutorials. Building that along with reading the docs (as opposed to cloning a repo) is best IMO.


djgreedo

>sometimes that’s like reading a dictionary Great analogy. You can't learn to read and write from a dictionary, but it's a great resource. I much prefer tutorials that contextualise and explain things. Most documentation is so poor I don't even think to look there first.


barsonica

Personally, I have problems understanding documentations. I need a tutorial to understand how things work, and then I use documentation to look up classes and their members.


TinyLebowski

Documentation can also mean a Getting Started guide with code snippets and examples. When they're well written I prefer these over third party tutorials.


barsonica

ye, that's true. But those are missing in most documentation or they are written by someone who completely understands the code in question (probably wrote it) and thus they forget to explain many things that are obvious for them.


jobblejosh

So many people forget the time in school when they were told to write an instruction book for 'an alien who only knows $local_language'. Documentation should explain what the modules do to someone who has never used the module before. Everything has to be in minute, line by line, argument by argument detail. If I've read your documentation and don't understand the importance of everything I've written then your documentation is not documentation.


[deleted]

[удалено]


lord_have_merci

if you have trouble understanding the documentation, its a problem with the documentation, not you. and i think thats part of the problem the OP is trying to get at.


arbolitoloco

looking at you fucking ReactJS!!!!!


chronicideas

Cries in Unreal


Quasar471

Unity Editor namespace : Aight Imma head out.


Thomasedv

Don't forget key code examples, love reading the python documentation because it's well explained stuff and then some code examples. Seeing something used helps so much when dealing with lots of different objects that work with each other.


maldini94

Especially if there's a cookbook included. Often the aha-moment of a framework/library is when you properly understand how to glue different concepts together Vue.js comes to mind as a great example.


lpreams

For most frameworks, what I really want is a simple example project that idiomatically uses the most common features of the framework/library/language/etc. Once I have a starting point, solid documentation is great for moving forward. But just starting with the documentation and no initial frame of reference can take a lot longer to get going. In lieu of good example code, a class or tutorial on getting started is the next best thing.


thinker227

When the documentation also includes tutorials and examples.


Gluomme

I still feel that 30 minutes of following a course or a tutorial is the best jumpstart you can have, before diving head first in the documentation


jeffwsoares

Say this to docker documentation


Dayv1d

Here is a guy who hasn't been laughed in the face for telling a manager that he needs 30 % more time on the ticket for proper documentation, yet.


Nashibirne

I think it doesn't make super much sense to compare documentation with online courses, because they serve entirely different purposes. If you want to know what framework X does, if it fits your problem, what the core principles and the architecture are, then articles and videos do their job. If you have already a grasp of the architecture and you want to know how to solve a specific task, then it is documentation. That being said, if an entire lecture series is necessary to explain a framework, something is off ...


imaginateinventify

The .Net documentation drives me nuts, it's completely fragmented now after so many rapid iterations of the framework and the links and examples are obsolete within days of them being added and just ping you around lots of different out of date resources.


SatoshiL

huh? never had problems with the .NET documentation, and I used it like 5 or 6 years.


zeropointcorp

Bet you’ve been using 4.5 the whole time /s


johnfrian

I only experience this problem when checking legacy code. My experience with most .net documentation has been good, are you perhaps working with older frameworks or using bleeding edge classes? Not trying to prove you wrong, just asking to become aware of any potential issues in the documentation on msdn


Okichah

At least it exists.


Octopork

The docs are expansive but 80% of pages are a barely up do date if your lucky hello world tutorial that generally belong on /r/restofthefuckingowl, it's hell to find intermediate information or even just finding what todays DI extension method or this weeks azure library to do something is. They need a cull and a refocus on being a useful resource first rather than trying to show off their bajillion features.


Janjis

Let me introduce you to Azure Cosmos DB which is now at v3.something. Each version bringing major changes. Docs not specifying which version it is for. Sometimes you have to go through half the page to understand what version it is about.


Kidplayer_666

Guizero is one of my favourite libraries as it is soooo darn well documented and easy to use, specially for noobs like myself


coolgamer2354

Sadly, well written documentation doesn't exist. Better pay for the online class I guess.


khaledsalem999

even if you learn it through a course or something, terrible documentations will always be a plague, I have been using NG-zorro library at work for our angular project, as good as the library is, the documentation is a total horrid mess, and I probably will never use it outside work ever.


Muaddibisme

You guys have documentation?


Attileusz

a course is very good for getting started but the moment you start doing anything serious documentation diving begins


rufreakde1

I miss examples of usage in documentation. Many times the wording is so bad that without an example its hard to be understood „directly“. ImGood documentation is explaining well the functionality and also provides examples!


DudeGuy123458

learncpp has been pretty good so far


anarchouser666

why spend 10 mins reading documentation when you can spend 10 hours debugging


Reformedjerk

I just manually browse the available methods in Visual Studio.


Flater420

Documentation is great for a targeted lookup. What's the setting for X again? Does this do Y or Z when offline? Courses and presentations are much better for getting a lay of the land when you don't have enough of a mental framework to form concrete targeted questions yet. So I disagree when "learning a framework" implies learning from scratch, but I very much agree that by the time you're an expert, you will have relied on documentation more than a course, assuming both were available and informative.


Plantelo

Which is why I love C#. It, and all of its close-by relatives (Unity, .NET, ASP, MSSQL, WPF etc.) have excellent documentation with code samples, simple explanations, and comprehensive information about their usage. Also Microsoft's docs page is navigable, I'm looking at you Oracle


seekster009

Am i the only one who finds microsoft's documentation difficult to understand?They just can't give simpler examples?


error_98

Java spring. We knew enough CS to realize the tutorial used tech we didn't need/want. We didn't know enough spring to selectively take the unnecessary parts out. But there were no docs. Only "how to set up spring websockets with STOMP and SockJS".


CSlv

You guys read the documentation?