You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -21,31 +21,31 @@ Believe me, your fellow software builders are wondering, experimenting, or alrea
21
21
22
22
{: .pull-right}
23
23
24
-
I’ve found that the principles inherent to the social web for coding work extremely well for documentation. The social web, leads to social coding, leads to social documentation.
24
+
I’ve found that the principles inherent to the social web for coding work extremely well for documentation. The social web leads to social coding, leads to social documentation.
25
25
26
26
# What is GitHub?
27
27
28
28
29
29
{: .pull-left}
30
30
31
-
Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for theLinux kernel. Read the history in the excellent [Pro Git Book](https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git).
31
+
Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for the Linux kernel. Read the history in the excellent [Pro Git Book](https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git).
32
32
33
-
GitHub is the web interface for `git` the command-line tool, that works well on Linux, Mac, or Windows. To work with others on a project (code or docs), you merge files. This model is the opposite of using a “lock and checkout” model, where no one else can work on the piece at the same time as you. With GitHub, you can work separately and bring it all together later. Git has a non-linear branching model that can take some learning to get used to. That said, I've found git and GitHub for docs quite practical and even inspirational.
33
+
GitHub is the web interface for `git` the command-line tool, that works well on Linux, Mac, or Windows. To work with others on a project (code or docs), you merge files. This model is the opposite of using a “lock and checkout” model, where no one else can work on the piece at the same time as you. With GitHub, you can work separately and bring it all together later. Git has a non-linear branching model that can take some learning to get used to. That said, I've found git and GitHub for docs quite practical and even inspirational.
34
34
35
-
You can keep docs in a source code repository then the developers will review all your changes prior to merging them in. Unlike traditional source code management, branches are not full copies of entire code base so they are “cheap” and “fast.” The more Agile techniques are applied to documentation, the
36
-
more treating docs like code makes sense.
35
+
You can keep docs in a source code repository then the developers will review all your changes before merging them in. Unlike traditional source code management, branches are not full copies of the entire code base so they are “cheap” and “fast.” The more Agile techniques are applied to documentation, the
36
+
more treating docs like code make sense.
37
37
38
38
# GitHub definitions and parallels for information
39
39
40
40
I hope I'm talking to people who care a lot about words. Let's start with some vocabulary and definitions to build upon.
41
41
42
-
* Branch: Indicator of divergence from base without changing the main line (or "trunk" if you like to visualize organic tree-structures to remember this term).
43
-
* Commit: Point-in-time snapshot of repository with changes.
44
-
* Fork (noun): Copy of the repository that is entirely yours in your namespace. In GitHub-land, forking does not have a negative connotation that it can in other contexts (such as taking an opensource project in a new direction in a huff to get different contributors). Rather, it is a way to contribute openly and publicly with your account attributed.
42
+
* Branch: Indicator of divergence from the base without changing the main line (or "trunk" if you like to visualize organic treestructures to remember this term).
43
+
* Commit: Point-in-time snapshot of the repository with changes.
44
+
* Fork (noun): A copy of the repository that is entirely yours in your namespace. In GitHub-land, forking does not have a negative connotation that it can in other contexts (such as taking an open-source project in a new direction in a huff to get different contributors). Rather, it is a way to contribute openly and publicly with your account attributed.
45
45
* Fork (verb): Making a copy of the repository.
46
46
* Issue: Defects, tasks, or feature requests.
47
47
* Organization: Collection of group-owned repositories.
48
-
* Pull Request: Comparison of edits to see if team wants to accept changes.
48
+
* Pull Request: Comparison of edits to see if the team wants to accept changes.
49
49
* Push: Move changes branch-to-branch. When you type `man git` at a Terminal prompt to read the [manual page for Git](https://www.kernel.org/pub/software/scm/git/docs/git.html), you see "Update remote refs along with associated objects," but that's more technical than we need here.
50
50
* Repository: Collection of stored code or documentation that is written and built like code.
51
51
* Review: Do a line-by-line comparison of a change, much like an editor would for documentation, and comment on improvements or changes.
Let's admit it. Writing in isolation sucks. No one to bounce ideas off of, to tell you when you're flat-out wrong or a terrible typist. Happens in organizations all the time: assignments thrown over a wall, deliverables that are project-centric instead of user-centric. The hardest can be when deadlines set by development, not docs or quality assurance, so those deliverables are always squeezed for time at the end. Less context, less empathy, less collaboration. What to do?
15
+
Let's admit it. Writing in isolation sucks. No one to bounce ideas off of, to tell you when you're flat-out wrong or a terrible typist. Happens in organizations all the time: assignments thrown over a wall, deliverables that are project-centric instead of user-centric. The hardest can be when development set deadlines, not docs or quality assurance, so those deliverables are always squeezed for time in the end. Less context, less empathy, less collaboration. What to do?
16
16
17
-
All these downfalls can be avoided when you collaborate where your readers and makers live—on GitHub. I say, go beyond content curation and curate the audience itself! Write with and for the audience. Have a developer write for her fellow developers. Make sure users have a way to share tips with each other through the documentation.
17
+
All these downfalls can be avoided when you collaborate where your readers and makers live—on GitHub. I say, go beyond content curation and curate the audience itself! Write with and for the audience. Have a developer write for her fellow developers. Make sure users have a way to share tips through the documentation.
18
18
19
19
As Andy Oram said so well in "Educating computer users: the need for community/author collaboration," "...the *value* in educational content lies in *context* (what immediate problem the reader is trying to solve) and *timeliness* (what’s true today will be outdated tomorrow)."
20
20
@@ -29,7 +29,7 @@ When you write with people beyond your immediate team, ensure that those contrib
29
29
* Produce effective, time-saving, user support.
30
30
* Build a reputation, recruiting.
31
31
32
-
Harnessing these needs being met is not about gaining free labor. Contributors should be highly, highly valued, and rewarded. It's about creating opportunity to shine, and curating jobs. Because contributor graphs are available on GitHub, and because the contribution data can be mined to see that reputation being built one pull request at a time, GitHub gives rewards in a new way.
32
+
Harnessing these needs being met is not about gaining free labor. Contributors should be highly, highly valued, and rewarded. It's about creating opportunities to shine, and curating jobs. Because contributor graphs are available on GitHub, and because the contribution data can be mined to see that reputation being built one pull request at a time, GitHub gives rewards in a new way.
33
33
34
34
If you think this all sounds nice but impractical, I encourage you to sign up for the newsletter to learn how to practice these techniques like you would a musical instrument. You need hands-on experience and time to play to get better and better.
@@ -39,7 +39,6 @@ To take it a step further, you can also add a link to edit the source doc file i
39
39
40
40
In traditional enterprise doc systems, writers can go weeks without getting reviews or input. Even when asking and nagging multiple times, sometimes the documentation systems are so separate from code systems that technical reviews are through email. GASP. Put those days behind you and go where the technically knowledgeable people are.
41
41
42
-
Working in the same collaboration tools as technical people gives better reviews. We can merge as many as 50 patches per day, though in reality it's about a dozen a day. We are running up to four automated doc tests per patch and requiring two humans to check the patch and click in order to publish. Each reviewer who can publish must adhere to our review rules, and people follow the rules really well.
43
-
42
+
Working with the same collaboration tools as technical people gives better reviews. We can merge as many as 50 patches per day, though, in reality, it's about a dozen a day. We are running up to four automated doc tests per patch and requiring two humans to check the patch and click to publish. Each reviewer who can publish must adhere to our review rules, and people follow the rules well.
A few years ago we went house-hunting in Austin, Texas. One house was so popular during the first showing, there were six back-to-back appointments. We waited in the driveway while another couple toured it. Once they left, we could quickly go through it while another prospective buyer waited on the front walkway.
15
+
A few years ago we went house-hunting in Austin, Texas. One house was so popular during the first showing, that there were six back-to-back appointments. We waited in the driveway while another couple toured it. Once they left, we could quickly go through it while another prospective buyer waited on the front walkway.
16
16
17
-
This house was awful. Every single surface was ugly, out-dated, and circa 1973. There was a giant hole in dirt by the front porch, likely dug by an animal. But you know what? I loved it. I wanted to bring it back to a vibrant family home, taking it back from the rogue porch-dwelling raccoons— or was it dirt-digging armadillos? We may never know.
17
+
This house was awful. Every single surface was ugly, outdated, and circa 1973. There was a giant hole in the dirt by the front porch, likely dug by an animal. But you know what? I loved it. I wanted to bring it back to a vibrant family home, taking it back from the rogue porch-dwelling raccoons. (Or was it dirt-digging armadillos? We may never know.)
Let’s look at your code base and your doc base as a great house with a good layout and foundational “bones.” You still need that “punch list” to hand to your contractor. When you move towards more docs like code techniques, make sure you treat your doc base like a code base, and track defects. Get that “punch list” done.
22
22
23
-
With a code base, you know how much remodeling you need to do. The same thinking can work well for docs. How dated have your docs become? How accurate are the docs compared to the rest of the code base? How can you make the site livable and vibrant again?
23
+
With a code base, you know how much remodeling you need to do. The same thinking can work well for documentation. How dated have your docs become? How accurate are the docs compared to the rest of the code base? How can you make the site livable and vibrant again?
24
24
25
25
Let’s give your readers the chance to do those quality checks for you as easily as possible: by reporting the bug on the page where they found it.
26
26
@@ -32,9 +32,9 @@ This technique works well when:
32
32
* You want your docs to be more trustworthy by chipping away at a bug backlog.
33
33
* You have a private GitHub repo for documentation, but you want to enable public bug reports with tracking back to your docs repo.
34
34
35
-
Your quick win is to look at your current docs site, any given page. Is there a way to report a bug publicly, to add to the “punch list?”
35
+
Your quick win is to look at your current docs site, on any given page. Is there a way to report a bug publicly, to add to the “punch list?”
36
36
37
-
1.Bare minimum starter level would be an email address link from every page.
37
+
1.A bare minimum starter level would be an email address link from every page.
38
38
1. Level up by adding a link to your GitHub source repo Issues page so readers can report bugs.
39
39
1. Better yet, write a quick bit of code to embed on every output doc page so that the issue is pre-filled with relevant information.
40
40
@@ -44,5 +44,4 @@ Here are some resources to get your first punch in that punch list:
44
44
* Using a private repo for docs, but want to track bugs publicly? Use [Issues-only Access Permissions](https://help.github.com/articles/issues-only-access-permissions/).
45
45
* Want to add a bit of code to pre-create Issues to use as comments on every page? Free yourself from Disqus comments. Try this [set of tips and sample code in a blog post](https://zpbappi.com/jekyll-with-tags-archive-and-comments-in-github-pages/).
0 commit comments