Comment by pfix | Hacker News Reader

Comment by pfix | Hacker News Reader

Parent Full thread

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