[HN Gopher] You Should Write a User Guide
___________________________________________________________________
You Should Write a User Guide
Author : opsgal
Score : 115 points
Date : 2020-12-22 14:08 UTC (8 hours ago)
(HTM) web link (boringstartupstuff.com)
(TXT) w3m dump (boringstartupstuff.com)
| intrasight wrote:
| You should not have a popup asking for my email.
| intrasight wrote:
| 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.
| MattGaiser wrote:
| I don't think you read the article. "User guide" is not what
| you think it is in this context.
| [deleted]
| intrasight wrote:
| 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).
| madamelic wrote:
| 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.
| bonoboTP wrote:
| I like my praise without the p.
| onei wrote:
| 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 wrote:
| 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.
| AtlasBarfed wrote:
| 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.
| fullshark wrote:
| 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.
| unabst wrote:
| 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.
| opsgal wrote:
| 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.
| gk1 wrote:
| 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.
| boringcomment wrote:
| you SHOULD write a user guide! If you liked this article, please
| share!
| the_cramer wrote:
| 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
| hnarn wrote:
| > 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.
| layer8 wrote:
| 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 wrote:
| 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).
| mindhash wrote:
| 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.
| musingsole wrote:
| 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.
| dkersten wrote:
| 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)
| alexchamberlain wrote:
| 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.
| dkersten wrote:
| 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).
| alexchamberlain wrote:
| 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.
| AtlasBarfed wrote:
| 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.
| malwrar wrote:
| 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.
| phkahler wrote:
| >> 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.
| dkersten wrote:
| 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.
| xapata wrote:
| Don't change jobs for that. Same problem everywhere.
| jasonpeacock wrote:
| What's the alternative to ticket walls? What would
| competent management look like in this case?
| 0xbadcafebee wrote:
| '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.
| dkersten wrote:
| 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 wrote:
| 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.
| ironchef wrote:
| 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.
| im3w1l wrote:
| 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.
| Sodman wrote:
| 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.
| caminmccluskey wrote:
| 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-...
|
| [Edit: Grammar]
| matthewh806 wrote:
| You Should Stop Telling People What To Do
| saddlestrap wrote:
| 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".
___________________________________________________________________
(page generated 2020-12-22 23:01 UTC)