Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Opposite of Documentation is Superstition (2020)

buttondown.com

Post reply on HN
Print view View original

21–30 of 87 posts

Re: The Opposite of Documentation is Superstition (2020)

#21

Post by pfix »

ChrisMarshallNY wrote: post #12

He's really talking about the user's mental model, here. I've found that it is sometimes a good idea to reinforce mental models that don't actually reflect the operation of the software (in my case) under it. Documentation is good, but, in my experience, almost no one ever reads it. I can tell, because of all the questions that I get, that are in the docs. That's totally my fault. A really good tech writer could prob…

Both is important. And related. Documentation needs to be discoverable. I was amazed when I tried jj (jujutsu, the "new git") and it popped me into some kind of weird textual user interface after executing `jj split` and I felt lost. I guessed, pressing `?` won't hurt and it told me just to use the mouse. The menues showed the related hot keys.

But the actual documentation of the tool has room for improvement. I needed a YouTube video to get started and that's rare for me.

So what I want to say is, that you need an intuitive, discoverable UI, but also a documentation that has each case (and if it's just for linking in 1st level support cases) _and_ is discoverable. And by that I mean both easy to grasp (e.g. following https://diataxis.fr/) and also can actually be found. I've had cases where a tool had good documentation, but actually finding it was the hard part.

Re: The Opposite of Documentation is Superstition (2020)

#23

Post by GuB-42 »

One also could say that the opposite of open source is superstition.

It works with the example given in the article: OneNote is proprietary software, and it is documented, though incompletely. Had it been open source, one could see exactly how shape recognition works, bugs, quirks and all. No documentation will give that amount of detail.

Sure, not everyone has the time and skills for that, but maybe someone on stackoverflow does and have answered the question with proof, that is, not a superstition.

Re: The Opposite of Documentation is Superstition (2020)

#24

Post by throwaway14356 »

IgorPartola wrote: post #20
Animats wrote: post #15

I've called this ritual-taboo programming for decades. It happens for user interfaces and APIs when the documentation is absent, or only consists of examples. If there's no reference documentation, everything is a copy of something someone else did. Nobody understands how it really works. Now, for some interfaces, this isn't too bad. Most people don't know why US AC power plugs are polarized, or what the ground prong…

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 basi…

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.

Re: The Opposite of Documentation is Superstition (2020)

#25

Post by Noumenon72 »

shizzy0 wrote: post #14

Some of the best technical documentation I’ve ever written has straight up lies in it. Granted they were placed there in the service of distilling the most germane portions of the API I was trying to explain. But it made a huge difference once I decided my code in the library didn’t have to be my code in its documentation. I felt a little like a biographical writer who makes a composite character. But honestly I reco…

Do you mean you just left out required args, try-catches for checked exceptions, and so on, so the example would be easier to read? Did you put an asterisk on, like "* illustrative code: will not compile"?

Re: The Opposite of Documentation is Superstition (2020)

#27

Post by throwaway14356 »

pfix wrote: post #21
ChrisMarshallNY wrote: post #12

He's really talking about the user's mental model, here. I've found that it is sometimes a good idea to reinforce mental models that don't actually reflect the operation of the software (in my case) under it. Documentation is good, but, in my experience, almost no one ever reads it. I can tell, because of all the questions that I get, that are in the docs. That's totally my fault. A really good tech writer could prob…

Both is important. And related. Documentation needs to be discoverable. I was amazed when I tried jj (jujutsu, the "new git") and it popped me into some kind of weird textual user interface after executing `jj split` and I felt lost. I guessed, pressing `?` won't hurt and it told me just to use the mouse. The menues showed the related hot keys. But the actual documentation of the tool has room for improvement. I need…

our architects love building the house before making the drawings. i imagine we will probably figure it out eventually when the feature set can be strictly defined.

(maybe you eventually want a bath tub and a toilet in each room? maybe not?)

Re: The Opposite of Documentation is Superstition (2020)

#29

Post by ChrisMarshallNY »

throwaway14356 wrote: post #27
pfix wrote: post #21

Earlier quoted context omitted.

Both is important. And related. Documentation needs to be discoverable. I was amazed when I tried jj (jujutsu, the "new git") and it popped me into some kind of weird textual user interface after executing `jj split` and I felt lost. I guessed, pressing `?` won't hurt and it told me just to use the mouse. The menues showed the related hot keys. But the actual documentation of the tool has room for improvement. I need…

our architects love building the house before making the drawings. i imagine we will probably figure it out eventually when the feature set can be strictly defined. (maybe you eventually want a bath tub and a toilet in each room? maybe not?)

I wouldn't call it "love," more than "necessity."

It really depends on the nature of the project, but UI design often requires a lot of "Paving the Bare Spots"[0]. It's really just too damn complex and counter-intuitive (or too intuitive) to catch in Requirements.

Software allows us to iterate this incredibly quickly. Hardware design also does it, but at a much slower pace, and a much greater cost.

[0] https://littlegreenviper.com/the-road-most-traveled-by/#pavi...

Re: The Opposite of Documentation is Superstition (2020)

#30

Post by ChrisMarshallNY »

Right now, I'm working on a SwiftUI project that displays charts of various statistics for our app system.

The docs for SwiftUI are ... less than ideal.

I'm pretty sure that it can do what I need, but the docs don't cover it at all. I'll need to keep playing with code completion (which kinda sucks, right now, because Xcode keeps making up nonexistent APIs), and looking at the actual system exported headers.

I'll get it, eventually, but this is pretty crazy bad.

Post reply on HN