Hacker News Reader

Comment by ChrisMarshallNY | Hacker News Reader

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 probably do a better job of conveying information.

That said, I think that it's important to present good, discoverable UI, that doesn't punish users for exploring.

View on HN

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.

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...

I've got architectural plans for my house. Parts of them are useful, but most of it isn't because the house doesn't match the plans. The details on the plans for the parts that match aren't trustworthy, because of all the parts that don't match. This is a relatively new construction, with minimal remodeling; it's just as they were building, they decided to do something else, and not update the drawings.

This is different than commercial work where in addition to the original plans, you also get as-builts, which can be expected to be accurate, and are expected to be updated.

If you only want to document once, it makes sense to do it once the thing is built, rather than before, because there's a good chance the actual thing will be different than the plan. If you will update it, it might make sense to start documentation before the thing is built.

Of course, if you never get around to writing documentation, it never needs to be updated.

Reply on news.ycombinator.com