Live data from Hacker News

You Should Write a User Guide

boringstartupstuff.com

21–30 of 45 posts

Re: You Should Write a User Guide

#21
post #11
post #9

Earlier quoted context omitted.

Even if they don’t read (software) documentation at first, it’s good to have something to point them to when a question or issue comes up. After that happens a couple of times, some may even learn that consulting the documentation is a useful thing to do.

Speaking from experience, if you're working with professionals (not always the case, of course), if 4/5 times your answer is just a polite link to a piece of documentation, over time they will start checking that documentation first. Like someone else said though, a lot of times the documentation just isn't any good. And just because it's great for a developer doesn't mean it's even useful for a VP Sales (for example…

I had a similar experience. It does reduce the calls after a while. Some people will still not get it, thats ok.

I also tried posting video walkthroughs for those who don't read. Okish response.

Re: You Should Write a User Guide

#22

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…

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.

Re: You Should Write a User Guide

#23

Every time this is posted, I go against the grain and agree with something like this. I think having general principles written down and available for your team or especially your manager is good. - How do I like praise? - How do I like criticism? - What makes me feel appreciated? etc. Your manager's job should be to keep you happy and productive. Knowing what makes you productive and happy at a company is their job.…

I like my praise without the p.

Re: You Should Write a User Guide

#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 appreciate it.

Re: You Should Write a User Guide

#25

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…

You are 100% right, documentation can't fix it. Having been involved in onboarding acquisitions into a larger parent company, it's been eye-opening to see how much of this is driven by culture.

The parent company's culture may be patient, contemplative, considerate, and proactive. They know it takes a long time to get things done and that everyone is busy. They open tickets, do research, seek advice from multiple groups. They double-check that they did something correctly, having learned that entering something incorrectly leads to it taking longer to get done. They check your slack status, and follow up after a few days if they don't get a reply e-mail.

But sometimes an acquisition's culture is quite different. A lot of 'drop everything right now, I need you to do something for me'. Using '@here' a lot and directly pinging people for non-urgent things. Or leaving a comment in a ticket like 'the backend team needs to fix this' but not going to the actual team to tell them they need to fix it and how. If they don't get a reply to an e-mail, they might wait forever.

None of this is due to good or bad people. The acquisition culture can be changed over time to the parent company's culture. But there needs to be a concerted effort to teach and exemplify the culture, though cooperation, trust, and leading by example.

Rather than a 'user guide', you can have informal discussions with groups and agree on some common communication strategies. You can discuss how different forms of communication affect you and build empathy within your team. And if the team ends up wanting varying ways of communication, then you can write user guides and publish them somewhere. The agile approach is more about building culture collaboratively and informally, and documenting what comes out of that as a de-facto standard.

Re: You Should Write a User Guide

#26

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.

I liked it though because you could track the progress on the ticket instead of pinging people periodically to see what the status is. Once I got used to it, I found it was a much simpler way to get things done across teams.

Re: You Should Write a User Guide

#27

Every time this is posted, I go against the grain and agree with something like this. I think having general principles written down and available for your team or especially your manager is good. - How do I like praise? - How do I like criticism? - What makes me feel appreciated? etc. Your manager's job should be to keep you happy and productive. Knowing what makes you productive and happy at a company is their job.…

As a former manager I felt like the first 90 days, even as long as the first 6 months, after onboarding a new employee was spent trying to figure out what motivates them, how to communicate with them effectively. One of the hardest parts of manager is managing someone who likes their praise/criticism presented in a drastically different way than you.

Most managers I've had in the past don't make the effort or make a pretty small effort to adjust based on the individual. I've spent a lot of time managing up in the past to mitigate this.

Re: You Should Write a User Guide

#28

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…

OP here - I actually agree with this sentiment to some extent . There's a thin line between "here's a shortcut to all the things you might learn about me over time anyway" and "I think my preferences are more important than yours."

Ultimately the exercise was helpful for me because of what I learned about myself and not because of what others could learn about me.

Re: You Should Write a User Guide

#29

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.

'Ticket walls' can be used as efficient pipelines for work. The problem is the teams who are asking for tickets aren't managing them correctly or don't have a good working agreement with the users. This is unfortunately very common with internal service providers.

But it can be changed. The users have to have a conversation with the service provider about what's wrong with the process, how it's affecting the users (& the business), and how they'd like it to change. If the service provider stonewalls them, they can go up the management chain. Often upper management has no idea what's going on and will get something done if they hear enough people complain.

Re: You Should Write a User Guide

#30

Every time this is posted, I go against the grain and agree with something like this. I think having general principles written down and available for your team or especially your manager is good. - How do I like praise? - How do I like criticism? - What makes me feel appreciated? etc. Your manager's job should be to keep you happy and productive. Knowing what makes you productive and happy at a company is their job.…

I like my praise without the p.

I enjoyed the wit of this but I think there's an important point. Employees provide a given amount of value to an employer and if they aren't recognising when that value increases, I'm sure someone else will. Words are nice, but money speaks more.
Post reply on HN