Feedback on Idea Jolters

Re: https://docs.google.com/document/d/177YrqXs6DzGFeOpey1eGmSMJZ3pWHOpZPil2yIU_x7c/edit#

Are we answering “Doc Downers”:

Hannah McKenzie 13:50 14 Nov Common examples of doc-writing negativity:

let's start with "DO NOT BE AFRAID" we're here to help! (from Ruth)

My writing's not good enough.

Hannah McKenzie 13:50 14 Nov writing isn't (slightly easier to read)

1 My writing's not good enough. 2 My English is poor. 3 I hate writing.

Hannah McKenzie 13:51 14 Nov suggest combining points 1 and 3

My English is poor.

Tips could include asking a more confident english speaker to review your work. Trying to think of a way to phrase this so that it sounds supportive, rather than a negative review or corrections Paul Foxworthy 14:40 14 Nov Yes. There should be testing and review for all of our artifacts :) Dylan Lacey 14:30 14 Nov Maybe we can start from code-based examples with minimal markup?

I hate writing. Dylan Lacey 14:31 14 Nov I'd approach this from the "Final Leg" direction - If you don't write docs, the other work is basically wasted. Docs are the thing that take a project for maybe OK to good.

It's not my job anyway.

Anonymous 14:32 14 Nov Like quality, it is everyone's responsibility. Should be part of your 'definition of done' Will be of value to your support team. Will providing documentation increase adoption of your tools / integration / whatever ? Is there a business driver for this?

Writing docs isn't as important as writing code. Anonymous 14:34 14 Nov Testing is also not part of writing code, but you still do it ;) Writing docs can be part of the software development process. Part of your 'definition of done'.

I'm busy.

Josh Sherwood 13:53 14 Nov What's the purpose or next steps if you identify these?

Can we help with answering:

Hannah McKenzie 13:53 14 Nov These points seem like a repeat of the above points.

Docs are dead - just make a video.

Paul Foxworthy 14:29 14 Nov Video with commentary is of necessity in one language and difficult to internationalise and localise. Video is difficult to search and has accessibility issues. If video is the ideal medium, encourage people to consider adding bookmarks for sections within the video (e.g. with WebVTT https://www.w3.org/TR/webvtt1/), and transcripts. Even an automatically generated transcript is way better than nothing.

Well-written code is its own documentation.

Paul Foxworthy 14:30 14 Nov To a subset of your audience.

Nobody reads the docs anyway, so why bother?

Dylan Lacey 14:38 14 Nov People do read docs, as long as they have confidence in their utility and they can access the information they need. Docs need to be useful when used while angry.

Writing docs is time-consuming and hard.

Paul Foxworthy 14:34 14 Nov Anything worth doing takes time. It's an investment. Of course there's a cost-benefit analysis to be done, but good docs can have a big payoff.

Won’t this lead to fewer technical writer jobs?

Paul Foxworthy 14:39 14 Nov I don't understand the point you're trying to make here. Will these templates lead to fewer tech writer jobs? No, just more productive tech writers. Are you suggesting that giving these templates to developers will mean devs do more of the documentation, so less need for specialists? I doubt that will happen. When it's important enough, people with expertise in communication will add significant value. Who is the audience for this question? Tech writers worried about their job security? I wonder if you could drop this question altogether.

thegooddocsproject / templates

Feedback on Idea Jolters #93