You Should Write a User Guide
boringstartupstuff.com
boringstartupstuff.com
- 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 mails.
I shoud remark that i do not work for a software-house but in medium scale distribution. Still did not find a way to communicate to my peers on how important phases of concentration and defined communication channels are. In my opinion, another documentation is not gonna work...
edit: formatting
Sure, people don't like it, but after a few attempts to bypass the system, they learn and stop doing it. (This is in a software company)
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).
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.
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.
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.
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.
So making quality software would not eliminate the need for them or the need for them to manage incoming requests.
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.
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).
/That said, there's always someone who develops the heuristic that asking you is faster. So, don't be.
I also tried posting video walkthroughs for those who don't read. Okish response.
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.
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 documentation.
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.
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.
Then adhere to these principles strictly and consistently. Others will notice and change the way they interact with you accordingly.
For example, with a few exceptions, I don't answer emails on weekends. It only takes one or two weekends for someone to realize this, and either stop emailing me on weekends or learn to not expect an answer until Monday.
As another example, if an important request, decision, or question is sent to me on Slack or text, I kindly ask them to send it to me by email. A few instances of this and people figure it out. This is, I think, a much more friendly way of changing people's behavior than pointing them to a user guide.
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.
Maybe I am just a weirdo Millenial who hates corporate places but if my manager or colleagues laughed at this or anything in that sort, I would leave since that signals a poor environment that is not about teamwork and being caring of others.
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.
This exposes way too much personal information.
For hiring it may flag HR paranoia.
The level of detail suggests self-awareness that psychology has shown to not exist in practically all people, or it will be a platform for career posturing like your resume and linked in.
So you're either lying to yourself, or lying to other people.
I also decided to write up a short piece on the pros and cons + some advice if you are considering writing a User Guide (or README or Personal User Manual) - https://medium.com/better-programming/personal-user-manuals-...
[Edit: Grammar]
Ultimately the exercise was helpful for me because of what I learned about myself and not because of what others could learn about me.
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.
In my experience, well-behaved colleagues will be considerate of my preferences. If I would prefer they change in some way, it's easy enough to have a quick conversation about how _they_ prefer to be contacted/scheduled and then, in turn, communicate my preferences as well. I'm sure they would read and follow my user guide, but I'd rather take the opportunity to spend a few minutes of facetime to build the relationship.
For poorly-behaved colleagues, I can't imagine them reading a user guide like this. If they don't care for my preferences, why would they spend time reading my user guide? They have already established that they are less considerate of my preferences. In that case, I've had success giving them a firm but very polite "no".
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.
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.
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.
Just joking. Do whatever you want - it's a free country (mostly).