4 ms·

How do you view self-documenting interfaces? Have you ever read the manual for your browser which you are using to make this comment? The OS on which the brows

How do you view self-documenting interfaces? Have you ever read the manual for your browser which you are using to make this comment? The OS on which the browser is running? The device on which they are running? I think there are interfaces that need to be usable assuming documentation will not be read. These are of course user interfaces, not necessarily APIs. But if you are creating something like a library of basic math functions I would rather read your code than your docs. Some of the worst docs I’ve read lately have been for ffmpeg and mp4box. The former sometimes straight up has things like “so one guy tried this and it worked for him so we recommend you try it and see how it works for you”. The latter has like 4 examples with no explanation of what you are looking at or how to make anything else work. The project used Stack Overflow for their docs because nobody can really figure out what to do with it right away. I’d rather take readable code in this case over the terrible docs.

throwaway14356 2y ago
writing great documentation is extremely hard. sometimes it is so well done you only notice it in how fast and easy you progress. the funniest opposite was documentation i wrote myself but turned out to complicated for the future self. i kept thinking, what is this guy on about?? it assumed the reader knew all kinds of things i didn't and it made effort to explain the obvious.
lelandbatey 2y ago
> How do you view self-documenting interfaces? > Have you ever read the manual for your browser which you are using to make this comment? The OS on which the browser is running? The device on which they are running? Have you ever read the manual for the tools used to build the building that you live in? A manual for the trowels, tape, mud, and drywall that built and makes up your walls? Or a manual for the Romex in those walls? A manual for the concrete foundation of your building? No? That's because using/depending on those things doesn't require nearly anything of you; you stand on the floors and lean on the walls without thought. You browse the web constantly, so you do it without thought. Not so with your taxes, despite their similar constance and ubiquity, because they are not constant and thus haven't had the same abstractions engineered into their very DNA. But even things like buildings/floors/doors with that level of "no need to think about them" only afford that to you based onto their frequent use. Few other pieces of software afford that same consistency. With time though, they will. I think we'll see a lot of software grow to be everore of a "skin round a spreadsheet", especially as we comoditize the few remaining frontiers of UX design (e.g. mobile devices) in the same way as desktop design has converged on common patterns like the chat-log-and-history, the search bar, the photo gallery, the text editor, and the spreadsheet.
- yearolinuxdsktp 2y ago
  What are you talking about with taxes? They have quite a few abstractions in them—-capital gains income, dependents, just to name two. I am laughing at ‘remaining frontiers’ of UX design. This year for Christmas I wish for mobile devices with browsers that don’t crash and lose my form entry. This year, I wish for YouTube that doesn’t find new ways to turn on autoplay (TV queue being the latest one I had to turn off, despite having already turned off AutoPlay on that device in settings… each of my devices has autoplay turned off… yet TV queue came with autoplay turned on… crooked YouTube!) But sadly, this kind of thing is not what the state AGs are looking at—-but to me, the constant bypassing of disabled AutoPlay is anti-consumer AF and must be stopped. That is the remaining frontier.
- fao_ 2y ago
  > You browse the web constantly, so you do it without thought. Not so with your taxes, despite their similar constance and ubiquity, because they are not constant and thus haven't had the same abstractions engineered into their very DNA. In the UK, the government automatically takes tax out of my income and tax is indicated as part of my pay cheque. It requires absolutely no thought from me.
- IgorPartola 2y ago
  Ironically, I have read parts of the international building code when I needed to build the building from which I wrote that comment, foundation to studs to Romex to drywall, and also lots of instructions printed on things like bags of concrete, drywall tape, etc., but never for a browser or a mobile phone. I guess you could infer where I think my expertise lies and where it doesn’t. :)
sahmeepee 2y ago
> Have you ever read the manual for your browser which you are using to make this comment? The OS on which the browser is running? For niche situations, yes, e.g. different browsers having different keyboard shortcuts for hard refresh. It's quite common for people to assume they know how to do it in one browser because they knew the shortcut in another, but when they just get a normal refresh they don't realise their error. Software written to be used by billions of people per day must be written to have a very low barrier to entry, and even if it contains sophisticated and complex features they must not be essential for >99.99% of the software's overall usage. The downside of this approach is that many people never learn about features in everyday software that would make them much more productive. Keyboard shortcuts as above are the classic example and are almost always documented, but there are many more unexplored features and not all requiring significant memory or technical skill to make use of. I've not heard of a regular office job in the last 15 years where there would be induction training on the core tools (OS, browser, office suite). It's assumed that you're not employable if you don't know how to use them, and by implication that knowing how to use them is a binary thing rather than a spectrum.
- IgorPartola 2y ago
  You have read the actual manual for your browser? Multiple browsers? You didn’t google for the answer on how to refresh the pages? Somehow I just don’t feel like this is the literal truth.
  - sahmeepee 2y ago
    If you mean a printed book describing how every feature of (say) Chrome works, then no. They don't produce one. The "manual" for Chrome is Google's support Web pages for the browser, which I have read in conscious preference to the often inaccurate folk knowledge that comes back from a general Google search.
brabel 2y ago
> But if you are creating something like a library of basic math functions I would rather read your code than your docs. Talking about software specifically: this is the exact wrong way to do it. A programming interface should be easy to use and "self-documented" to some extent (by, e.g. using the type system as much as possible to make bad states unrepresentable), but only very simple interfaces are usable that way. For most real-world interfaces, there's just no way you can encode all the "rules" in the type system and the names. You absolutely need to document how your interface works in general, what each part is used for and expected to do, special cases and so on that are just impossible to know otherwise. Now, if you just read the implementation instead (and notice that you would need to read all implementations, most interfaces are likely implemented in many different ways) you're not coding against an interface at all. You're assuming the implementation is the interface. You're ignoring what the implementer intended to be private and subject to change. Don't do that.
- jajko 2y ago
  Yeah thats a horrible approach that creates massive additional costs down the line, usually not author's problem anymore though. Can't really put finger on it precisely, maybe its too large ego (my time is too valuable for some pesky documentation for idiots, I am a superstar! No you're not, you are at vee best a brilliant junior...). Or maybe lack of basic empathy, surprisingly high number of humans can over time learn how to work in society but any novel situation requiring some empathy they handle like mammoth ina porcelaine shop. Or something else in similar vein. That was quite shocking, entering adulthood and discovering vast number of folks have such issues
  - dingnuts 2y ago
    I used to write a lot of comments and I don't much anymore. Usually a long comment is a smell. If the way something works isn't obvious and must be explained, it can probably be better designed. Code changes and then comments have to be updated, and often aren't. If they aren't just wrong, the context is often so changed that they aren't useful. You wind up reading the legacy code anyway, and you and the author both wasted time with comments. My team is smart and competent. I need them to read the code to make sure their changes are safe, anyway. They do not need their hands held. They don't need me to waste time writing comments that will soon be outdated, or that explain something I should have designed better. Finally, management doesn't apply an OKR to intangible code metrics like internal documentation. Should they? I don't know, but it's their code, not mine, so I'll write it to the standard they apply. These are the reasons you have to work in code that is poorly documented. It has nothing to do with a lack of empathy -- if I were to allow my employer to extract extra value from me by using my empathy for my teammates as a lever that would be exploitation. If I spend more time on documentation -- which the employer doesn't value -- instead of functionality, I'll be punished at review time for wasting time on worthless things. Maybe you should stop letting your company manipulate you into doing more work than they're paying for. If they value internal documentation, they'll create an OKR or KPI or whatever to make sure you're paid to do it. Otherwise it's unpaid labor for a for profit corporation. I'm not doing that. Are you?

throwaway14356 2y ago

writing great documentation is extremely hard. sometimes it is so well done you only notice it in how fast and easy you progress. the funniest opposite was documentation i wrote myself but turned out to complicated for the future self. i kept thinking, what is this guy on about?? it assumed the reader knew all kinds of things i didn't and it made effort to explain the obvious.

lelandbatey 2y ago

> How do you view self-documenting interfaces? > Have you ever read the manual for your browser which you are using to make this comment? The OS on which the browser is running? The device on which they are running? Have you ever read the manual for the tools used to build the building that you live in? A manual for the trowels, tape, mud, and drywall that built and makes up your walls? Or a manual for the Romex in those walls? A manual for the concrete foundation of your building? No? That's because using/depending on those things doesn't require nearly anything of you; you stand on the floors and lean on the walls without thought. You browse the web constantly, so you do it without thought. Not so with your taxes, despite their similar constance and ubiquity, because they are not constant and thus haven't had the same abstractions engineered into their very DNA. But even things like buildings/floors/doors with that level of "no need to think about them" only afford that to you based onto their frequent use. Few other pieces of software afford that same consistency. With time though, they will. I think we'll see a lot of software grow to be everore of a "skin round a spreadsheet", especially as we comoditize the few remaining frontiers of UX design (e.g. mobile devices) in the same way as desktop design has converged on common patterns like the chat-log-and-history, the search bar, the photo gallery, the text editor, and the spreadsheet.

yearolinuxdsktp 2y ago
What are you talking about with taxes? They have quite a few abstractions in them—-capital gains income, dependents, just to name two. I am laughing at ‘remaining frontiers’ of UX design. This year for Christmas I wish for mobile devices with browsers that don’t crash and lose my form entry. This year, I wish for YouTube that doesn’t find new ways to turn on autoplay (TV queue being the latest one I had to turn off, despite having already turned off AutoPlay on that device in settings… each of my devices has autoplay turned off… yet TV queue came with autoplay turned on… crooked YouTube!) But sadly, this kind of thing is not what the state AGs are looking at—-but to me, the constant bypassing of disabled AutoPlay is anti-consumer AF and must be stopped. That is the remaining frontier.
fao_ 2y ago
> You browse the web constantly, so you do it without thought. Not so with your taxes, despite their similar constance and ubiquity, because they are not constant and thus haven't had the same abstractions engineered into their very DNA. In the UK, the government automatically takes tax out of my income and tax is indicated as part of my pay cheque. It requires absolutely no thought from me.
IgorPartola 2y ago
Ironically, I have read parts of the international building code when I needed to build the building from which I wrote that comment, foundation to studs to Romex to drywall, and also lots of instructions printed on things like bags of concrete, drywall tape, etc., but never for a browser or a mobile phone. I guess you could infer where I think my expertise lies and where it doesn’t. :)

sahmeepee 2y ago

> Have you ever read the manual for your browser which you are using to make this comment? The OS on which the browser is running? For niche situations, yes, e.g. different browsers having different keyboard shortcuts for hard refresh. It's quite common for people to assume they know how to do it in one browser because they knew the shortcut in another, but when they just get a normal refresh they don't realise their error. Software written to be used by billions of people per day must be written to have a very low barrier to entry, and even if it contains sophisticated and complex features they must not be essential for >99.99% of the software's overall usage. The downside of this approach is that many people never learn about features in everyday software that would make them much more productive. Keyboard shortcuts as above are the classic example and are almost always documented, but there are many more unexplored features and not all requiring significant memory or technical skill to make use of. I've not heard of a regular office job in the last 15 years where there would be induction training on the core tools (OS, browser, office suite). It's assumed that you're not employable if you don't know how to use them, and by implication that knowing how to use them is a binary thing rather than a spectrum.

IgorPartola 2y ago
You have read the actual manual for your browser? Multiple browsers? You didn’t google for the answer on how to refresh the pages? Somehow I just don’t feel like this is the literal truth.
- sahmeepee 2y ago
  If you mean a printed book describing how every feature of (say) Chrome works, then no. They don't produce one. The "manual" for Chrome is Google's support Web pages for the browser, which I have read in conscious preference to the often inaccurate folk knowledge that comes back from a general Google search.

brabel 2y ago

> But if you are creating something like a library of basic math functions I would rather read your code than your docs. Talking about software specifically: this is the exact wrong way to do it. A programming interface should be easy to use and "self-documented" to some extent (by, e.g. using the type system as much as possible to make bad states unrepresentable), but only very simple interfaces are usable that way. For most real-world interfaces, there's just no way you can encode all the "rules" in the type system and the names. You absolutely need to document how your interface works in general, what each part is used for and expected to do, special cases and so on that are just impossible to know otherwise. Now, if you just read the implementation instead (and notice that you would need to read all implementations, most interfaces are likely implemented in many different ways) you're not coding against an interface at all. You're assuming the implementation is the interface. You're ignoring what the implementer intended to be private and subject to change. Don't do that.

jajko 2y ago
Yeah thats a horrible approach that creates massive additional costs down the line, usually not author's problem anymore though. Can't really put finger on it precisely, maybe its too large ego (my time is too valuable for some pesky documentation for idiots, I am a superstar! No you're not, you are at vee best a brilliant junior...). Or maybe lack of basic empathy, surprisingly high number of humans can over time learn how to work in society but any novel situation requiring some empathy they handle like mammoth ina porcelaine shop. Or something else in similar vein. That was quite shocking, entering adulthood and discovering vast number of folks have such issues
- dingnuts 2y ago
  I used to write a lot of comments and I don't much anymore. Usually a long comment is a smell. If the way something works isn't obvious and must be explained, it can probably be better designed. Code changes and then comments have to be updated, and often aren't. If they aren't just wrong, the context is often so changed that they aren't useful. You wind up reading the legacy code anyway, and you and the author both wasted time with comments. My team is smart and competent. I need them to read the code to make sure their changes are safe, anyway. They do not need their hands held. They don't need me to waste time writing comments that will soon be outdated, or that explain something I should have designed better. Finally, management doesn't apply an OKR to intangible code metrics like internal documentation. Should they? I don't know, but it's their code, not mine, so I'll write it to the standard they apply. These are the reasons you have to work in code that is poorly documented. It has nothing to do with a lack of empathy -- if I were to allow my employer to extract extra value from me by using my empathy for my teammates as a lever that would be exploitation. If I spend more time on documentation -- which the employer doesn't value -- instead of functionality, I'll be punished at review time for wasting time on worthless things. Maybe you should stop letting your company manipulate you into doing more work than they're paying for. If they value internal documentation, they'll create an OKR or KPI or whatever to make sure you're paid to do it. Otherwise it's unpaid labor for a for profit corporation. I'm not doing that. Are you?