- 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...
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 it might be in there, but with the note that if its not covered in the docs, to let them know. Usually it was in the docs.
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)
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).
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.
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.
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.
>> 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.
'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.
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.
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'll echo this from my experience managing development tools for a 40 person team. At first, someone is asking you questions because the tool is new, no one knows where resources on it might be, but they do know you work on it. If this continues, it's because whatever non-you resources that are available aren't answering questions adequately. So change/update the docs until they can answer the questions for you.
/That said, there's always someone who develops the heuristic that asking you is faster. So, don't be.
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.
Maybe beans should be assigned to unwanted contact attempts. Then the bean counters can count them at the end of the quarter, and see if the phone calls were a net gain or loss of beans.
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 documentation.
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.
> 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.
If pointing colleagues to a "Gk1 User Guide" feels self-centered or weird for any reason, call it "Operating Principles" and keep it internal.
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.
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.
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.
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.
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.
Just seems like something from a far more ideal world that isn't cutthroat capitalism and information warfare.
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 went back and forth on whether it was a good idea. In the end I wrote one and it was well received by my team. Indeed, most of the team wrote one and we collated them in our documentation space. This was pretty helpful in the first few months of lockdown, when people's work preferences and constraints were quite varied.
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.
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.
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.
The idea of a "User Guide" sounds nice for a small team or company, as the author mentions. I would caution against the approach for anything larger.
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".
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.
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.
I do wholeheartedly agree about user guides. But I'll rephrase the statement as "Your documentation team should write a user guide". If your big enough to need a user guide, you're big enough to have a documentation team. That can be a team of one for starters. Comparative advantage. Programmers should program.
In addition, I'll say that your documentation team should use real technical writing software like FrameMaker and not some lame ascii markup thingy like Markdown, RST, etc. Programmer written documentation should be embedded in their code.
Just joking. Do whatever you want - it's a free country (mostly).
- 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