10 ms·

You Should Write a User Guide

• boringcomment 6y ago
  you SHOULD write a user guide! If you liked this article, please share!
• the_cramer 6y ago
  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 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
  • ironchef 6y ago
    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.
    • the_cramer 6y ago
      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.
  • im3w1l 6y ago
    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.
  • layer8 6y ago
    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.
    • pc86 6y ago
      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).
      • musingsole 6y ago
        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.
      • mindhash 6y ago
        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.
  • dkersten 6y ago
    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)
    • AtlasBarfed 6y ago
      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.
      • dkersten 6y ago
        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.
      • 0xbadcafebee 6y ago
        '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.
  • 0xbadcafebee 6y ago
    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.
  • hnarn 6y ago
    > 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.
• matthewh806 6y ago
  You Should Stop Telling People What To Do
• saddlestrap 6y ago
  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".
• intrasight 6y ago
  You should not have a popup asking for my email.
• intrasight 6y ago
  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.
  • deleted 6y ago
    [deleted]
  • MattGaiser 6y ago
    I don't think you read the article. "User guide" is not what you think it is in this context.
  • intrasight 6y ago
    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).
• caminmccluskey 6y ago
  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. 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-the-good-the-bad-and-the-template-7b80db5044ea https://medium.com/better-programming/personal-user-manuals-... [Edit: Grammar]
• gk1 6y 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.
• madamelic 6y ago
  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.
  • AtlasBarfed 6y ago
    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.
  • bonoboTP 6y ago
    I like my praise without the p.
    • onei 6y ago
      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.
  • Taylor_OD 6y ago
    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.
• fullshark 6y ago
  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.
  • opsgal 6y ago
    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.
  • unabst 6y ago
    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.
• Sodman 6y ago
  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.
• hinkley 6y ago
  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.
• simonblack 6y ago
  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.