Technical Writing - your questions!

[beardofedu]

Hello everyone! I'm Matt Desmond and I'm a trainer here at GitHub. I was asked to host a training on Technical Writing (like I did for the Fall Campus Experts). I'm super excited to answer any and all questions you may have about project documentation, technical writing in general, and other questions you might have.

So, before the training occurs, I wanted to give everyone an opportunity to ask questions before the training:

We're looking ahead at the next talks! One of the suggested topics was technical writing.

What questions do you have about technical writing? This could be documentation, blogging, articles, books, any form of writing for technical people or on technical topics.

Drop your questions below!

cc: @joenash

[elliotblackburn]

👋 @beardofedu, super excited for this talk! Here are some questions, I might add a few more later as well as I come up with them!

• What are some common mistakes people make in things like project README's or documentation aimed towards people using and developing for the project?
• If I create a new library, I tend to make a blog post to help demo the use case a bit. Is there a rough structure structure you've noticed which works best for this? Such as, is it sensible to talk about the use case first, or are code snippets best placed towards the top?
• Within an open source project, what tends to be the most useful form of documentation? I'm wondering where might be best to spend time, perhaps architectural overviews in a wiki or maybe it's code level comments, perhaps auto-gen docs, or the README.
• What sort of tools do you tend to use in different types of documentation? Most of my docs are markdown and blog posts, is there something big I'm missing out on?

Feel free to take any good questions and leave the rest!

[abdulajet]

👋🏾 @beardofedu one question I have to do with blogging, is how to deal with varying skill levels of readers.

[joenash]

I'd love to hear a bit about voice for technical writing. Both in terms of style, and also active vs passive voice

[beardofedu]

What are some common mistakes people make in things like project README's or documentation aimed towards people using and developing for the project?

So, I searched for "awesome README files" to show what great projects are doing and I immediately started nitpicking the sites this [repo](https://github.com/matiassingers/awesome-readme) selected as "awesome".

Quick breakdown of some sites:

• gaze - putting the release notes in the README seems like an incoherent use of space. They could just as easily link to their release notes that are hosted elsewhere. This would reduce the length of their README.

• bluebird - putting the license in the README seems redudant. The license is available in the link at the top of the repo and as a file within the repo.

• pageres - Why list the API content in your README? Just link to content about your API. As the scope of your project expands, having solid API documentation outside of a text based list will be helpful for your users.

• httpie - So. Long. Can't. Stop. Scrolling. The README has a lot of great information with an emphasis on A LOT. The README could build a solid GitHub Pages-based website.

So, my thoughts on README files and documentation in general (without stepping on Jenn's section):

• Step Back
  Disconnect yourself from how "you" use your project / product and identify how an end user is going to use it. If you can't think of it, ask a friend, preferably someone who isn't making as many commits as you to the project.
• Right Place, Right Time
  If you were looking for content on "how to do an advanced function", would you look on the same page that described how to "install the service"?
• Delivery Methods
  The beauty of Git is the ability to work without an internet connection, however, if I'm learning new content without an internet connection and you only provide content online, how can I learn how to use it while, say on a plane? Create a really basic "print friendly" version of your content for your users.

---

If I create a new library, I tend to make a blog post to help demo the use case a bit. Is there a rough structure structure you've noticed which works best for this? Such as, is it sensible to talk about the use case first, or are code snippets best placed towards the top?

Without an example (which is not a big deal), I have a couple of suggestions:

• Describing why I would use your library should be first, I don't care about your code snippets if I don't know why I would use it.
• Think of the top X (maybe try to hit 3) use cases for your library / product / project and identify the process to complete that.
• Use other projects as an example for what you want to do and what you do not want to do.

---

Within an open source project, what tends to be the most useful form of documentation? I'm wondering where might be best to spend time, perhaps architectural overviews in a wiki or maybe it's code level comments, perhaps auto-gen docs, or the README.

If I had to organize your "documentation plan" into a sort of NEED to NICE to have list, it would look something like this*:

• README, project introduction, primary contacts, how to contribute, install instructions
  • Getting Started Guide - probably created when README starts to become "too big"
• For an API, I think Apiary[www.apiary.io] looks pretty solid, but, a GitHub Pages site for your API can look pretty solid as well.

Bottom line, make it easy for other contributors to assist with content creation. Maybe start a GitHub Pages site and if you need to scale up, check out Apiary or one of their competitors? I just learned about them recently, so I'm fairly new to that specific space.

*disclaimer: the type of project you are working on will most likely alter the importance of your documentation deliverables.

---

What sort of tools do you tend to use in different types of documentation? Most of my docs are markdown and blog posts, is there something big I'm missing out on?

I used to use Flare, which was an XML / HTML documentation tool that would create Online and Print content from the same source content. It was a GUI environment and I'm a Windows user, don't hate me. From Flare, I moved to Indesign to create mammoth text book files and didn't get to digital very much. Now, I write primarily in Markdown, actually, I do everything in Markdown at this point.

---

One question I have to do with blogging, is how to deal with varying skill levels of readers.

10-30-60.

10% of your users are going to be advanced and potentially be subject matter experts on your product(s) for their company / local group

30% of your users won't know how to use your project without very detailed documentation and will require the most assistance if your content is missing basic concepts. As an example: I had created hospital software documentation that in 2007 still needed documentation on what a mouse was. 🖱 :

60% of your users are going to have the technical accumen to pick up your product and use it with some help. Spend your time here.

---

I'd love to hear a bit about voice for technical writing. Both in terms of style, and also active vs passive voice

On Style:

I prefer not to take myself too seriously, so my documentation typically doesn't either. My primary goal is identify the expected outcome and get the reader there. If I use 17 terrible git puns along the way, they are probably better because of it.

Active vs Passive:

• Use Active if: the user needs to do something
• Use Passive if: someone needs to do something

I'm pretty terrible at active vs passive conversations, so I'm going to let this random blog provide insight: random blog

On Grammar:

• Pick a style guide and "use it". "Use it" meaning, try really hard to use it in your content, but if you miss an Oxford comma, the world isn't going to end. However, if you click buttons, don't tell people to press them on another page. Consistency is really important, especially with instructions.

---

If you have made it this far. 🙇

Link: for Mindmup

[juanpflores]

Hey @beardofedu 👋
I've been using the .github folder on my repos to create issue and PR templates for anyone that wants to collaborate. Even do I've been using them for a while something that is not clear when it's recommendable to add the folder and templates and what a good Issue/PR template should have and look like.

[beardofedu]

@juanpflores maybe check out the PR and Issue templates we are using in the Training Kit repo to get some ideas. Ideally, you want to make the directions clear and concise and provide as provide a roadmap for how contributors to your project should be framing their issues / pull requests.