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

You Should Write a User Guide

boringstartupstuff.com

Post reply on HN
Print view View original

31–40 of 45 posts

Re: You Should Write a User Guide

#31

Post by malwrar »

AtlasBarfed wrote: post #22
dkersten wrote: post #18

Earlier quoted context omitted.

I've interacted with teams that would commonly get messages in their slack channel asking to review PR's or whatever and the team would simply point at the channel status which was a link to their ticket submission page and the expected turnaround time, with a message like "Hi, please open a ticket and we'll get to it within the SLO", and then they strictly stuck to that. They also always linked the documentation if…

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 alternative model for dealing with these people I’m excited to hear about it.

Re: You Should Write a User Guide

#32

Post by jasonpeacock »

AtlasBarfed wrote: post #22
dkersten wrote: post #18

Earlier quoted context omitted.

I've interacted with teams that would commonly get messages in their slack channel asking to review PR's or whatever and the team would simply point at the channel status which was a link to their ticket submission page and the expected turnaround time, with a message like "Hi, please open a ticket and we'll get to it within the SLO", and then they strictly stuck to that. They also always linked the documentation if…

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's the alternative to ticket walls? What would competent management look like in this case?

Re: You Should Write a User Guide

#33

Post by alexchamberlain »

dkersten wrote: post #18
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…

I've interacted with teams that would commonly get messages in their slack channel asking to review PR's or whatever and the team would simply point at the channel status which was a link to their ticket submission page and the expected turnaround time, with a message like "Hi, please open a ticket and we'll get to it within the SLO", and then they strictly stuck to that. They also always linked the documentation if…

I really appreciate when someone takes a few minutes to answer my question on a public (rather than 1-1 chat), so I endeavour to do the same for others. Treat others as you'd like to be treated.

Re: You Should Write a User Guide

#34

Post by dkersten »

alexchamberlain wrote: post #33
dkersten wrote: post #18

Earlier quoted context omitted.

I've interacted with teams that would commonly get messages in their slack channel asking to review PR's or whatever and the team would simply point at the channel status which was a link to their ticket submission page and the expected turnaround time, with a message like "Hi, please open a ticket and we'll get to it within the SLO", and then they strictly stuck to that. They also always linked the documentation if…

I really appreciate when someone takes a few minutes to answer my question on a public (rather than 1-1 chat), so I endeavour to do the same for others. Treat others as you'd like to be treated.

Well, in this particular company, everything was public. Even the 1-1 discussions tended to be threads in the public slack channel. Or at least comments on the ticket.

The main point was if you want the other team to do something, you create a ticket so that they can schedule it in, rather than interrupting them demanding they drop whatever they might be doing to do your thing. And if your question is already addressed in the documentation, then its a waste of the teams time and energy to answer the same thing over and over.

If you have a legitimate question that isn't answered in the documentation, then you can absolutely ask and get an answer. The main goal is to reduce interruption with needlessly (everyone is busy!) and to reduce low quality low effort questions. Answers then often also made it back into the documentation.

So its not about treating the requester badly, but rather that its easy and low effort to ask someone to do or answer something, while it can be incredibly disruptive for the team being asked. This is a means of managing that, and in my opinion it worked great. It also pushed me to put enough effort into questions when I did have them (what am I trying to achieve, what have I tried, where have I looked for answers, what problems am I having).

Re: You Should Write a User Guide

#35

Post by unabst »

fullshark wrote: post #24

A colleague did this at a job of mine, I honestly found it obnoxious and presumptuous, this idea that it’s on me to consciously change my behavior to work with them instead of on them to deal with the tiny inconveniences and pet peeves that come from collaboration with someone. Maybe it helped and coworkers aren’t your friends so who cares as long as it does but beware if you do this that I don’t think everyone will…

It's this.

The developer mindset almost enjoys documentation because you can absorb it fast, in detail, and get on with the problem in the window next to it.

In the real world (TM), problem solving is often a matter of responsibility and a delegation issue and resolved socially. And often for non-developers, the software they are given is suppose to be the solution to all their other problems. So when there's a problem with the software or they can't understand it, a standard reaction is "which number do I call", "train me", or "can you fix this".

For client facing shops, the developer needs to document for customer service. Customer service needs to handle client/user communication. And customer service benefits most from detailed documentation, to allow them to answer user questions without asking the developer.

If this is a mixed collaboration environment, then communication needs management. There are people that want open channels. There are people that don't. And there are people that are offended when their preferences are not met or violated. Management is a requirement.

Re: You Should Write a User Guide

#36

Post by xapata »

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…

Don't change jobs for that. Same problem everywhere.

Re: You Should Write a User Guide

#37

Post by phkahler »

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…

>> What competence would make ticket walls go away?

I dont mean this as snark but how about making quality software that is easy to use and has good documentation.

More jokingly: Take down the walls and let some users actually bother developers with their problems until the developers fix those recurring annoyances just for their own sanity. This is probably going too far.

Re: You Should Write a User Guide

#38

Post by alexchamberlain »

dkersten wrote: post #34
alexchamberlain wrote: post #33

Earlier quoted context omitted.

I really appreciate when someone takes a few minutes to answer my question on a public (rather than 1-1 chat), so I endeavour to do the same for others. Treat others as you'd like to be treated.

Well, in this particular company, everything was public. Even the 1-1 discussions tended to be threads in the public slack channel. Or at least comments on the ticket. The main point was if you want the other team to do something, you create a ticket so that they can schedule it in, rather than interrupting them demanding they drop whatever they might be doing to do your thing. And if your question is already address…

This is why you should ask on a public chat; if I'm really too busy to read the Slack channel, I won't read the Slack channel. If, on the other hand, I need a breather or "I'm waiting for the compiler", I might be able to give you some pointers in the right direction or encouragement with what you've already discovered.

I'm not encouraging lazy questions per se; I want people to demonstrate effort (what have you tried?) and ask the right question (X-Y questions), but equally, I appreciate that documentation takes a long time to digest and maybe my opinion is what you want rather than discrete facts.

Re: You Should Write a User Guide

#39

Post by hnarn »

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…

> They do not read any documentation I write about me or my software.

It’s a vicious cycle. If you have bad documentation, people won’t read it, but without people reading the documentation no one wants to spend time writing it.

Even when you have good documentation (which by the way is decided by the readers, not the writers) you still need to educate users constantly that it exists and should be referred to.

I refer customers to documentation that is well written and almost always correct on a daily basis, and as soon as they understand where to look and know there aren’t gaps, they’ll start using it (because if there’s gaps and they need to contact support anyway, you might as well skip the doc step completely and get a correct response instead).

Documentation is one of those things that aren’t obviously necessary enough for most stake holders behind the scenes, and it only starts to hurt when you’re at the point where you wish someone started documenting a year ago.

Re: You Should Write a User Guide

#40

Post by dkersten »

phkahler wrote: post #37
malwrar wrote: post #31

Earlier quoted context omitted.

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…

>> What competence would make ticket walls go away? I dont mean this as snark but how about making quality software that is easy to use and has good documentation. More jokingly: Take down the walls and let some users actually bother developers with their problems until the developers fix those recurring annoyances just for their own sanity. This is probably going too far.

The "ticket wall" I was talking about in my original comment had nothing to do with quality software, but rather getting a team handling a different competency to do or answer something. The example I gave was actually for the "cloud automation" team, they handled such things as AIM roles/policies, cross-account AWS permissions and various other AWS/cloud services that other teams used. Other teams had similar "go through tickets" ways to interface with them, for example the team that handled the servers that CI got provisioned on. Developer-services teams that provide services to development teams internally, basically.

So making quality software would not eliminate the need for them or the need for them to manage incoming requests.

Post reply on HN