Planet Open Help

The life and work of the open help community
Join our planet

January 14, 2019

Anne Gentle Anne Gentle

Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.

GitHub Pro account or GitHub Free account for Technical Writing

Should I downgrade or upgrade my GitHub account, now that the free tier has unlimited private repositories? I could save seven dollars a month, 84 dollars a year.

I looked into this question for myself, and didn’t get enough info from the pricing page at when the change was first announced. So, I logged a help ticket with GitHub, and as I’ve experienced before when I was working on the Docs Like Code book, they were very responsive! I had an answer by the next morning in my inbox.
My specific question was, “What are ‘advanced code review tools,'” quoting from the pricing page. I must note: the great thing about asking this question is that I see that the pricing page now points to the answer to the question! The link is now available, and the text has changed to “Advanced tools and insights.” My inner product manager heart jumped with glee.

What do you get with the GitHub Pro Account?

What I learned is that the added features are related to many things that are useful for doc publishing and reviews, using private repositories on GitHub. These features and tools on your private repos include these, with links to help pages where available:

Now, you can do all those things on public repositories with your GitHub Free account. So what does this mean for people using GitHub for tech writing? I think it’s similar to any use case for development. If you want to work in private with more than three collaborators, and publish from a private repo to a public webpage using GitHub Pages, you want a GitHub Pro account. If you’re pretty sure you’re always going to work in public repos in the open, then you don’t lose anything by staying with a Free account.

For me, I’ll keep paying my $7 a month as I’ve found it super valuable to work through things either on my own or in small groups. I also like protected branches, sometimes for my own safety. And maybe, or at least I’d like to think so, I’m supporting students and starting users of GitHub by supporting GitHub itself.

by annegentle on January 14, 2019 11:44 AM

January 12, 2019

Anne Gentle Anne Gentle

Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.

Startup costs for writing a book on GitHub

What does it take to put together a web site, a book, an ebook, all for sale online? Let’s look at costs for tools and services that make it happen.

Let’s look at what you need for a book idea. You need an audience, an editor, a way to reach that audience, and a “pitch” for the book idea itself. You may chose self-publishing over pitching the book idea to a technical book publisher.

In my recent experience with Docs Like Code, the process led me to choosing to produce the site, epub, and printed book all using tools I had prior experiences with. Let’s take a look.

Reaching out to current contacts

First, I reached out to Andy Oram, a senior editor at O’Reilly who knows me from a couple of open source projects, asking if he thought O’Reilly would want a book proposal. He said he’d be happy to read what I had, but didn’t see the initial concept fitting into their current catalog. Really great of him to offer to help out, and I simply thanked him and kept going with my idea.

In parallel, I reached out to the publisher for my first book, Conversation and Community. His name is Richard Hamilton and he runs XML Press. When he looked at his schedule, he couldn’t read through at the draft copy for about 3 months. Well, I thought that the timing was essential, and I didn’t want to wait that long, knowing both the market and my own availability.

Finding like-minded collaborators

I also reached out to Diane Fleming, now Skwish, who had been teaching writers how to use Git and GitHub for docs over the same time as I had been. Over lunch, we realized we both wanted this book to be available for the next time we teach developers and writers how to write and review docs on GitHub. Diane is a talented writer and also a super editor. The best writers re-write a lot, and I knew Diane would provide an eagle eye for both technical accuracy as well as great writing.

Then, I realized I have a great friend in Kelly Holcomb, who edited my first book and I could talk her into editing this one, wahoo! Kelly also had experience in using GitHub for editing, so her contributions were super important for the final copy.

One area I did skip on for this book was a professional-level index, which Kelly was able to do for a great job on for Conversation and Community. I haven’t missed the index yet, and for a smaller book it seems like an index could look like padding.

Design materials and promotional work

I also was able to do all the design imagery myself, including the book cover. This part was thanks to Canva and some nice templates that service has online. I used the free trial for Canva to make the book cover and stickers and t-shirt design.

That said, I was not willing to take on the layout work myself. So, when Gitbook did not output a PDF that I considered “print-ready”, I went to Upwork. I wanted more fine-tuned layout and design for the print copy, including proper page breaks and nice tables. So I hired a designer with access to Indesign who could take the epub and turn it into a print book.

Pull it together!

And so, with all those bits of input from others, it created a quest to be a product manager for my own information product! I went that route, and for me, Lulu was a tool I was already familiar with because we had done publishing with it for OpenStack.

There are other publishing options – IngramSpark, Amazon, LeanPub, and I’m sure others. I did sign up and get approved for an account with IngramSpark, which is the print-on-demand service that XML Press uses.

To me, after reading the origin story for Lulu, I feel that Lulu is a bit more “open source” based than say, Amazon. I don’t know much about LeanPub. Since I was using Markdown on a private GitHub repo anyway, it doesn’t seem to offer more than Lulu for the marketplace reach. I’m not trying to make money at it; only trying to increase reach.

Finding a freelance editor would be a huge leg up on the writing process itself, especially if you also need a bit of developmental editing for the book idea.

For the print layout, I had a great experience with UpWork and was also able to keep the same person for work I needed one for the second edition. I learned from using a freelance site that I can find and manage freelancers for projects that I want to get done but don’t want to carve out time or buy tools for myself to finish them.

List of tools and services


Ongoing and startup costs

Here’s a high-level overview of the startup costs for creating a book like Docs Like Code. I calculated the starting costs for six or five months, when I needed a monthly subscription for a service.

Based on Lulu reporting, I see the book brought in about $2500 in 12 months of the first and second edition being available. So while the startup costs are not nothing, I did see a profit from the effort. Really, though, the effort is paid off in helping others see the benefits I’ve observed and in sharing and learning. Let me know what you think about this method, the tools, and of course, the resulting book, Docs Like Code, which you can buy online.

Domain name registration$20/year
GitHub for Private repo$42 ($7/month x 6)
GitBooks for Private repo$35 ($7/month x 5)
GitHub Pages for website$0
Canva for Work (cover art)$0 trial
Lulu (printed copies)$82 for 15 printed
Editing/Writing$250 celebration
Design for PDF layout$250
MailChimp (ongoing)$42 ($7/month x 6)
Twitter ads$25 for ads
Stickers$82 for 200
Total startup costs$828

First published on Docs Like Code at in April 2018.

by annegentle on January 12, 2019 12:13 PM

January 01, 2019

Anne Gentle Anne Gentle

Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.

Hone your writing skills or specialize? Observations from 2009

Never permit a dichotomy to rule your life, a dichotomy in which you hate what you do so you can have pleasure in your spare time. Look for a situation in which your work will give you as much happiness as your spare time.

Pablo Picasso

Someone pointed out a bit of a dichotomy in technical communication the other day. It was such an interesting observation that I’ve been thinking about it for a while. The dichotomy is between the power of plain old writing skills and the power of “sexier” specialized skills.

What are the specialties?

Directions for tech comm that  Tom Johnson and Alan Porter discuss on their respective blogs is a movement towards videos and screencasting (screencasts category on Tom’s blog) or graphics and illustrating (comics category on Alan’s blog). Updated to add: One that seems to be standing the test of time is the Google Chrome comic.

Mostly these posts talk about how users don’t read the manual (which is okay, in this post by Tom Johnson). Perhaps specialization is a wise direction to take, because specialization may not be taken over by “the crowd” as easily as writing., for example, was seeded with 20 professionally-produced how-to videos, and the community can add videos to the site as well. You can mostly detect which were made by professional film-makers, so it would appear they’re employable longer.

Content farms go moo

Since anyone can write, and content farms are impacting the web, filling it to the brim with quickly written, search-engine baited fast-food content, hone more specialized skills in order to thrive in the shifting sands of the web, right? However, content experts like Brian Massey say that all content, no matter the source, is what’s driving the successful websites and web applications today. The written word is still effective with measurable results, and is overwhelmingly more prevalent on the web today, page for page., for example, is a wonderful redistributor and aggregator of banking and investment accounts, a specialized type of content. Mint also creates content, such as the weekly summary newsletter, that encourages you to return to the site. This content is text and numbers, with lovely graphs, but it’s really the numbers that shine.

To summarize

With both sides pointed out to me now, I’m leaning towards the broader content strategy movement. I will help people get content from any source, even if it’s built by a community or (gasp) ordinary users. But I do see the value in video and especially in non-text-heavy mobile content as we roll into the new year and a new decade.

Here’s my observation. If it’s true that, the link shortener that’s popular on social sharing sites, has counted over a billion click-throughs per month, then it’s possible that social sharing will overtake search engine optimized content. As noted in 5 Trends That Will Shape Small Business in 2010, “Social search has the ability to eclipse the value of traditional SEO efforts.” A comment counters with the trend to go from text to video, saying clients should “record, record, and then record some more.” (Updated to add: This is certainly true, nine years later, though unexpectedly to the detriment of the internet as a whole.)

Let me repeat that. Eventually there could be more people reading and clicking through links on social sites than searching and clicking through links in search results. How will that shift change how you create content, and how will you strategically choose the content that you create?

I know the choices I have made in the last decade that have set me on the path of specialization, including community-sourced content, open source methods, and developer documentation including API specifications.

Originally published in December 2009, updated December 31, 2018. I think my favorite line is “Content farms go moo.”

by annegentle on January 01, 2019 01:14 PM

December 08, 2018

Lana Brindley Lana Brindley

Writes too much, reads too much, talks too much, thinks too much, drinks too much. Generally superlative.

Facebook, Dynamite, Uber, Bombs, and You.

This is the transcript of a talk I gave at WriteTheDocs Australia, in Melbourne, on 15 November, 2018. A video is also available, see the Videos page for a link.

This little story starts with the American son of German migrants, Herman Hollerith. He was born in 1860, got a degree in engineering, and then went to work in the US Census Bureau in 1879. At that time, the census was just a headcount, they didn’t collect any real data on the population, simply because they didn’t have the ability to process that information. As it was, they only ran a census every ten years, and it took them several years to process all the information. This meant that the big concern of the department is that before too long it was going to take them longer than ten years to do the calculation, meaning the next census would have started before the last one was complete. 

These days, we call that overwhelming technical debt.

So young Master Hollerith was a bit of a bright spark, says “there ought to be a machine for doing the purely mechanical work of tabulating” and set out to build one. By 1884, he had a prototype, and the US Census Bureau used the machines for the 1890 census.

Herman Hollerith, Bright Spark.

The data is first encoded on the punch card with the pantograph, then operators would load the card into the tabulator. Pins would drop down onto the card, and where there was a hole the pin would drop through and land in some mercury, which completed an electrical circuit, and advanced one of the dials on the machine. So each dial on the machine represents one character trait: age, gender, state, etc. Then the operator would record the data, remove the card and put it into a sorter drawer. Then they could reset the tabulator, ready for the next one. According to the US Census history site, operators could process 80 cards a minute this way.

Because Hollerith was a bit of a smarty pants, he didn’t sell the machines to the government, he leased them, and after a bit he managed to lease them to all sorts of government departments, all around the world, which was good to keep the money flowing in in between censuses. To handle this, he created a company called, creatively, the The Hollerith Electric Tabulating System.

Over the next few years, Hollerith’s company found other companies that were making “machines” like employee punch clocks and weighing systems, and they merged into a partnership called the Computing-Tabulating-Recording Company (CTR). That company then became International Business Machines in 1924, and the companies were finally all merged in 1933.

Anyway, there is a whole other talk on IBM corporate history, but the short version is that Thomas J Watson became IBM chairman in a ridiculously dodgy deal in about 1914 WHILE HE WAS IN JAIL, and remained so until he died in 1956. Because the guy was so dodgy, he didn’t like writing things down. I mention that, because it becomes important later in the story.

IBM Dehomag Hollerith D11 Tabulator

These are some early IBM machines made by the German IBM subsidiary called Dehomag. These machines were called the Dehomag Hollerith D11 tabulator and sorter. They were originally used primarily in banks to process account transactions, calculate interest, and – most interesting to the government of the day – cross reference bank account numbers to census data.

This was in about 1935.

IBM Dehomag Hollerith D11 Sorter

You know when you see pictures of people who have been in the concentration camps, and they have a number tattooed on their arm? Those numbers connected the human being to the punch card for a Hollerith machine. So here’s a fact: In Holland, they had extensive Hollerith machine infrastructure in the years before the war, and 73% of Dutch Jews were killed by the end of it. In France, they had very little Hollerith infrastructure, and what they had was disorganised. Only 25% of French Jews were killed by the end of the war. In short, without this technology, the Holocaust would still have happened, but it wouldn’t have been so well organised, so well planned, and so well executed.

Of course, I’m sure you all know about the Nuremberg Trials that happened after the war ended. We remember those for the Nazis who got sentenced for war crimes in the main trial, but there were 12 more trials between 1946 and 1949, which covered 177 people: physicians, judges, military personnel, civil servants and also industrialists.

Gustav Krupp and his friend Adolf Hitler

People like Gustav Krupp, who provided Panzer Tanks to the Nazis. Interestingly, it didn’t slow that company down much: you probably know them as ThyssenKrupp now. They make elevators. Anyway, so you would expect that senior officials in IBM would have ended up before the Nuremberg trials, too, but jokes on you!

The Nuremberg Trials were pretty unique, in that they had to be conducted in four languages, more or less simultaneously, which had never been done before. Guess who provided the computing power for that? Got it in one! Interestingly, for completely unrelated reasons, I was in Nuremberg a couple of months ago, and took the opportunity to go to the Documentation Center and Nazi Party Rally Grounds. It was a fascinating tour, but much to my dismay, IBM was not mentioned once.

Hopefully what you’ve picked up so far is that Hollerith was a brilliant young man who solved a very difficult problem. It’s not his fault that the technology he developed was used by Hitler to murder people. It’s also not his fault that not only was no one held responsible for that, but also that we seem to have collectively forgotten about it. The point I’d like to make, here, is that throughout history technology has been used in some pretty horrible ways. So let’s look at some more historical “oh no” moments …

Alfred Nobel, Repentant “Merchant of Death”

Alfred Nobel, you might recognise his name. He was the guy who invented dynamite, but he also owned a large weapons manufacturing plant. Anyway, Alfred’s brother died in Cannes, and a French newspaper got confused and wrote an obituary for Alfred instead. It was pretty nasty stuff, titled “The merchant of death is dead”, and this wonderful line: “Dr. Alfred Nobel … became rich by finding ways to kill more people faster than ever before”. So Alfred read this, had what is technically known as an oh no moment, and completely secretly went on to establish the Nobel prize with his personal fortune. Hilariously, he decided not to tell anyone about it, so they all got a nice surprise after he died for real, and they read his will.

Otto Hahn got the Nobel Prize for Chemistry in 1944 for working out Nuclear Fission. The prize really should have been given to him along with his two colleagues Lise Meitner and Fritz Strassmann, but the other two had had to leave Germany in a bit of a hurry a few years earlier. Later on, of course, that technology was used to bomb Nagasaki and Hiroshima, and the entire world had an oh no moment. Now we have ethics committees in Chemistry.

Eugenics was the practice of sterilising portions of the population in order to stop them breeding. Hitler was obviously a big fan, but before WWII it was a bit of a big deal in the US. 33 US states had sterilisation programs in place against mentally ill people, disabled people, alcoholics, people living in poverty, and people deemed to be promiscuous. Some reports say around 65,000 Americans were legally sterilised during the first half of the 20th century. That was a bit of an oh no moment for Biology. The World Health Organisation (WHO) was created in 1948, as the first specialised agency of the UN. It’s mission was multi-faceted, but I’ll draw your attention to this bit: “to address the underlying social and economic determinants of health through policies and programmes that enhance health equity and integrate pro-poor, gender-responsive, and human rights-based approaches”. 

Basically, don’t let our government kill you and tell you it’s good for  your health.

In a similar vein, some great drug failures like Thalidomide made the idea of having better oversight on medicines seem like a good idea. Thalidomide was sold over the counter from 1957, and was recommended to pregnant women for relieving the symptoms of morning sickness, unfortunately it created horrific birth defects. Only 40% of children born with defects survived, and those who didn’t were missing limbs. oh no. Court cases were brought against the manufacturer all over the world, including a class action in Australia as recently as 2012. The US Food and Drug Administration was created in 1927, but the thalidomide cases significantly strengthened its abilities, and a whole bunch of other laws around the world were introduced to address drug testing around the world.

We didn’t let too many bridges collapse before we decided that civil engineering could use some regulation. In America, the National Society of Professional Engineers was established in 1932, which adopted a formal code of ethics in 1964.

And it only took one plane flying into a building to establish that maybe letting people take box cutters on planes was less than sensible.

Hopefully you can see where I’m going here.

People very rarely come up with new ideas, new inventions, amazing new discoveries, with the intention of killing or hurting people. It’s the unintended consequences that cause the problems. But it’s also those unintended consequences – the “oh no” moments – that lead to improvements in the way we handle things. We end up with better laws, better regulations, and our society improves as a result.

Ethics committees and government oversight departments and legal rulings don’t stop bad things happening. But they can certainly help prevent them, and at least they give us some kind of recourse if the worst happens.

Now, I want you to consider these two cases: Volkswagen was caught out having written software code that allowed their cars to cheat emissions tests.

Uber also developed software (called ‘greyball’) which allowed them to cheat law enforcement officials trying to crack down on ride-sharing.

The difference is that Volkswagen software engineers went to jail, and Uber software engineers didn’t. Why? Because one is a car company, and one is a software company.

Startups especially like to use the phrase “move fast and break stuff”. In IT, we talk about “innovation” a lot, and “thinking outside the box”. I’m sure we all know a project manager who has encouraged us to “challenge paradigms” or “think different”. This is all great, and I’m not suggesting we should stop building new things, or thinking up interesting ways to tackle problems! But what happens when we step back from what we’ve created, and go … oh. No.

Really, in my opinion, IT should have its oh no moment when IBM provided the computing power that made the Holocaust possible, but not only did it go unpunished, we’ve largely forgotten about it over the intervening 80 years or so. So there’s never really been a public reckoning. So now we’ve looked at some examples of oh no moments leading to real change, let’s look at some aspects of IT innovation that haven’t …

The development of the world wide web in the 90s was obviously very optimistic, and I’m not sure we can blame anyone for failing to see 4Chan coming. But we can probably blame some of the social media sites for failing to see the dens of iniquity they have become, and we can certainly blame most of them for failing to do anything about it once it happened. Twitter’s response to the incredible amount of white supremacism has been at best ineffective and, at worse, non-existent.

I find self-driving cars a particularly thorny problem. On the one hand, there are huge benefits to the technology. Consider the implications not only on the environment and on the convenience it can add to our lives, but the added mobility and independence it would give people with disabilities means that this technology could add so much to our lives and to our society. But we haven’t fully thought through the impacts yet. Most of the accidents related to self-driving features so far have been because humans became too reliant on the tech, doing stupid stuff like watching movies, reading, or napping, instead of acting as a last-resort safeguard. What happens when we rely on the tech so much that we stop looking before we cross the road, because we “just know” the cars will stop for us? I have self-driving features in my car, and it makes stupid mistakes ALL THE TIME. The tech is not advanced enough for us to rely on it – driving is, after all, a life or death proposition every time you get on the road. But I also don’t think it should be hidden away until it’s perfect, because how else do you learn what “perfect” is? This is a tricky one.

I looked into the killer robots thing a few months ago, and that’s another tricky one, because the technology being developed for fully-automatic weapons systems, is also used for things like the afore-mentioned self-driving cars, aeroplane technology, medicine and surgery applications, and even peace-keeping operations, like dropping aid packages into war zones. In this case in South Korea, a university went into partnership with an arms manufacturer to develop autonomous weapons, and what ended up stopping them was a bunch of universities signing an open letter (which was initiated by an Australian academic, incidentally), threatening to boycott the university involved. The South Korean government wasn’t intending to step in, the UN didn’t step in. Without an ethics organisation, what other recourse is there to stop things? As it is, we don’t really know that the research has been stopped. The chancellor of the university wrote a lovely letter saying that, but the weapons organisation funding it could be quite happily moving along, and I wouldn’t be at all surprised if they had waved large amounts of money at academics to bring them into the project. That’s all speculation of course, but that’s really my point: there’s no oversight, no regulations, no repercussions, but there is a hell of a lot of money.

Here’s one more for you, that was reported in the Economist a couple of months ago, and has been picking up pace in the mainstream media recently: Xinjiang is a province in north-west China, largely occupied by the Uighur people. So, the Uighur are the largest Muslim group in China. In Hotan, the capital of Xinjiang, there is a police station every 300m or so. If you don’t think that already sounds like a police state, wait for this bit: every citizen has an identity card, and at checkpoints around the province, police will scan people’s cards, take photographs and fingerprints, perform an iris scan, and are told to unlock and hand over any smartphones, which are put into a cradle and the data downloaded to be analysed later on. That’s not just for people they’re suspicious of, they’re for everybody. There are four or five checkpoints every kilometre, with citizens moving through them many times a day. The roads are lined with poles holding cameras which watch pedestrians, but also perform pattern matching between number plates on cars, and the faces of the people driving. And if you’re Uighur and you have done even a relatively minor infraction then you get sent to one of hundreds of thousands of “re-education” camps in the province, which don’t officially exist. No one really knows how many people are locked up, but the estimate in the Economist article was 140,000 people in Hotan alone. The ABC in recent reporting says 2 million. So, locking up minority groups for no reason is by no means a new thing, but the way technology is being put to use in this case certainly is. I bet the people who invented facial recognition have had several oh no moments thanks, at least in part, to China.

In that same vein, you might also have heard of Palantir. They’re the company that use Minority Report-style predictions about crime in an area. It was originally developed for the Pentagon to identify terrorists in Iraq, but that technology has now been imported to downtown Los Angeles, where it’s being used to lock up brown people *before* they commit a crime. So it’s not just China.

So, while the increasing mainstream media awareness of personal data and the nefarious purposes we can put it to has been heartening recently, I’m not sure that Cambridge Analytica and Facebook are enough to be considered an oh no moment that will actually change anything in our industry, but I think it might be starting.

So, what does all this have to do with documentation?

You might be aware that, after quality assurance, the group that finds the most bugs in software is the documentation team. We are often put in the position of poking at products we don’t yet fully understand, in order to work out how to use them. It is the writer’s job to come at products like a clueless user, poke things, bend them, use them in ways they haven’t been designed.

I say we should expand that thinking just a tiny bit: how could I use this product to do harm? How could I use it to discover things about people I really shouldn’t be discovering? Can I use this social product to stalk my ex? What about someone who said something nasty about me online, can they find out anything important about me? Can I use this platform, this API, this plugin, this app, this feature to do something that, as reasonable moral human beings, we feel a little uncomfortable about? It’s also important to think about using it in conjunction with other tech. Recognising someone’s face is one thing, but when you combine that with GPS locations, government databases, and purchase history, you have a completely different problem. And also an answer to why I stopped using supermarket loyalty cards. Only last week I received an email confirming my booking for a hotel I hadn’t heard of. Curious, I clicked the link to ‘edit my booking’ and discovered that, while I couldn’t see the whole credit card number, I could have adjusted the dates of the booking, upgraded the room, or purchased additional services. All because someone mistyped their email in a form.

If I can give you one piece of advice, it’s don’t read your marketing department’s hype. Or if you do, don’t believe it. Nuclear fission has saved millions of lives through cancer treatment, provided light and power to billions, and made surgery and even vegetables safe through irradiation, that’s what the marketing department want you to know. But it also made nuclear war a real possible threat, and the marketing department is unlikely to mention it.

So, question things. Raise bugs. 

Talk about it with your development team, and your manager. Until software engineering has a real, honest to god, oh no moment, and an ethics board with actual legal teeth is born, you — the tech writer — are at the forefront between technology that helps, and technology that can hurt.

by Loquacity on December 08, 2018 05:41 AM


  • Anne GentleAnne Gentle Author of Conversation and Community: the Social Web for Documentation. I’m a writing fiend, technical geek, community doc nut, + Content Stacker for OpenStack.
  • Jim CampbellJim Campbell HRIS admin to the stars, and documentation writer for needy open-source projects. As a Chicagoan, I also know enough to not put ketchup on a hot dog.
  • Lana BrindleyLana Brindley Writes too much, reads too much, talks too much, thinks too much, drinks too much. Generally superlative.
  • Shaun McCanceShaun McCance GNOME documentation team lead. Programmer. Technical writer. XML expert. Community leader. Free software enthusiast.