You Should Write a User Guide • Hacker News Board

Re: You Should Write a User Guide

#11

Post by pc86 » Tue, Dec 22, 2020, 3:34 PM UTC

layer8 wrote: post #9

the_cramer wrote: post #3

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…

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).

Re: You Should Write a User Guide

#12

Post by [deleted] » Tue, Dec 22, 2020, 3:39 PM UTC

intrasight wrote: post #10

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]

Re: You Should Write a User Guide

#13

Post by musingsole » Tue, Dec 22, 2020, 3:42 PM UTC

pc86 wrote: post #11

layer8 wrote: 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'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.

Re: You Should Write a User Guide

#14

Post by MattGaiser » Tue, Dec 22, 2020, 3:54 PM UTC

intrasight wrote: post #10

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.

I don't think you read the article. "User guide" is not what you think it is in this context.

Re: You Should Write a User Guide

#15

Post by caminmccluskey » Tue, Dec 22, 2020, 3:55 PM UTC

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]

Re: You Should Write a User Guide

#16

Post by intrasight » Tue, Dec 22, 2020, 3:57 PM UTC

intrasight wrote: post #10

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).

Re: You Should Write a User Guide

#17

Post by gk1 » Tue, Dec 22, 2020, 4:08 PM UTC

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.

Re: You Should Write a User Guide

#18

Post by dkersten » Tue, Dec 22, 2020, 4:43 PM UTC

the_cramer wrote: post #3

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 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)

Re: You Should Write a User Guide

#19

Post by madamelic » Tue, Dec 22, 2020, 4:43 PM UTC

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.

Re: You Should Write a User Guide

#20

Post by AtlasBarfed » Tue, Dec 22, 2020, 5:34 PM UTC

madamelic wrote: post #19

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.…

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.