You Should Write a User Guide • Hacker News Board

Re: You Should Write a User Guide

#41

Post by Sodman » Tue, Dec 22, 2020, 10:27 PM UTC

In my opinion this is unnecessary for small teams, and doesn't scale to big teams.

Either your team is small enough that this should just be a conversation you have when you'd rather team members change their behaviors - OR - your team is too big to read and remember everyone's preferences.

Also, at the end of the day, the two people trying to communicate are either going to have similar preferences (Both morning people, both prefer talking over real-time video chat, etc), or they're going to have vastly different preferences (night owl, prefers async communication, etc). These user guides don't change anything in either situation, the person with more leverage is most likely going to "win" any decisions over how something ultimately gets communicated.

Re: You Should Write a User Guide

#42

Post by hinkley » Tue, Dec 22, 2020, 11:36 PM UTC

I wish I had a better phrase for "disagreeing by degrees", other than 'necessary, but insufficient'. You should write a user guide, but having a user guide doesn't provide anything other than a checkmark in a box somewhere.

What you should do is witness people using the documentation you provided. It's one of the most humbling experiences I've even willingly put myself through in a business setting, but the benefits are huge (can't say the same for some other experiences).

Without that you're in "something should be done, this is something, so we will do it" territory. You haven't proven anything until you can get a user through the docs without having to apologize a million times or dodge things being thrown at your head.

Critically, the quality of your code and product will improve, because you will discover that the emotional energy required to patiently apologize for some dumb limitation of your system is more expensive to you than the logistical energy of fixing the damned problem so you don't have to explain it.

We have the 5 Why's for production outages. For documentation, the 3 Why's are often sufficient for prioritizing fixing of bugs/misfeatures. This is part of the code is stupid because of Thing B. Thing B is that way because we cannot fix Thing C. Why can't we fix Thing C? No good (defensible) reason presents itself, or the reason is now gone. Well shit, let's fix it then, and put a paragraph in the release notes instead of the User Guide.

Re: You Should Write a User Guide

#43

Post by AtlasBarfed » Wed, Dec 23, 2020, 1:24 AM UTC

malwrar wrote: post #31

AtlasBarfed wrote: post #22

Earlier quoted context omitted.

Ticket walls are an unfortunate outgrowth of continued management incompetence in software development. Unfortunately, once it starts it spreads like the plague, and combined with defensive internal service monopoly empire building, results in anything being done taking 10x more as a task passes through a half dozen first layer and who-knows-how-many second layer ticket walls/SLOs.

What competence would make ticket walls go away? I’ve only ever had dayjobs with large orgs and ticket walls have been a useful defense against folks who insist on sending low-quality help emails or DMs the moment they encounter a problem. Sometimes I consider taking a massive paycut to work in a smaller company specifically to lessen the probability of needing to work with those sorts of people. If there’s some alte…

Aligning resources predictively to the needs of applications/projects. So if a project is about to go into intensive database development, you align a group of your DBAs to them for "preferential access".

Not just viewing the workers as completely interchangeable cogs, but getting them insight into specific applications, so requests can be processed more quickly.

Transparency into who is handling a request.

Managers scheduling and accepting enough "float" or unplanned work time to accommodate requests.

Educating developers to plan out their resources and requests.

Aligning support personnel to release schedules.

Re: You Should Write a User Guide

#44

Post by simonblack » Wed, Dec 23, 2020, 1:43 AM UTC

User Guides are not about you, or perhaps they need to be called something else.

A User Guide is something that you do to help other people. Your users in other words.

I dislike writing User Guides, but they're the only way to let other people know how to use your product.

Re: You Should Write a User Guide

#45

Post by the_cramer » Wed, Dec 23, 2020, 9:39 AM UTC

ironchef wrote: post #4

the_cramer wrote: post #3

My experience as a developer is - people don't care about my status (e.g. "busy", "dnd") - people don't care about my communication preferences -- if i'm not blocked they will call, no matter the priority - they are not interested in any priortization not done by them. And last and the most related to this approach: - They do not read any documentation I write about me or my software. They hardly read the contents of…

Maybe the documentation you've written hasn't been good? I've found well-written documentation to be a good way to avoid having folks bother me. I tend to treat it as a first class citizen artifact of my work (along with tests). Have it be as auto generated as possible. The above being said, I've also sometimes struggled to put myself in the user's shoes to understand what are the things I should emphasize in the doc…

Could be, yes, but how to find out? The users won't read it, and the only reason i get for that is "I don't have time for this, just tell/show me how it's done".

My user documentation is usually hand written and in a rather linear style, split by tasks. "You want to reach this goal, do the folling". On the other hand i am aware that as a developer, our style of submitting information to peers is sometimes different. Non-developers have a hard time to follow and sometimes a few explanation attempts are needed to get the information over the river (both ways).

This would tell me that an in-between person should create documentation. This person does not exist in my vicinity...

I will however take the feedback from this thread into account and point at documentations more often. Maybe it has an effect.