Hopefully the answer isn’t “none”! Let’s assume you’re writing documentation because you’re a wonderful person. Is it a comprehensive discussion of all the features in your software? Good…sort of.
There’s a place for in-depth, comprehensive reference documentation. And that place is often “over there in the corner collecting dust until someone really needs it.” By and large, people are going to need smaller, more task-focused docs. It’s a difference between reference guides and user guides. Or as I like to think of it: “what could I do?” versus “what should I do?” These are not the same documents.
“What could I do?” docs should be chock-full of facts that are easy to discover when you know what you’re looking for. They don’t have opinions, they just list facts. You go to them for an answer to a very specific question that has a correct answer.
“What should I do?” docs should be opinionated. “So you want to do X? The best way to do that is Y, Z.” They’re focused on accomplishing some use case that the reader can probably describe in human language, but might not know how to do technically.
A great example of “What should I do?” docs is the tldr project. Unlike man pages, which are generally reference docs, tldr-pages focus on use cases.
When I was more active in the HTCondor project, I often dreamed (sometimes literally) of writing a book about administering HTCondor pools. The developers had a great reference manual, but it often lacked the more opinionated “here’s what you should do and why.” It’s something we should all consider when we write documentation.
Gatekeepers are a problem in communities. They decide — often arbitrarily — who can and cannot be members of a community. Are you a true Scotsman? A gatekeeper will tell you. And if there’s something they don’t like about you, or they’re feeling particularly ornery, they’ll keep you away from the community.
Gatekeeping is a problem in open source communities. More experienced (or just louder) contributors set a bar that new contributors cannot meet. This is bad for folks who want to contribute to the project, and it’s bad for the project’s sustainability.
A recent Opensource.com article asked “What is a Linux user?“. In the initial version, it left open the possibility that if you’ve only used a Linux desktop that doesn’t require a ton of tinkering, then you’re not a real Linux user. Fortunately, the comments called this out quickly. And the author, to his credit, did not hold this view. He quickly updated the article.
The revised article does a much better job of closing the door on gatekeeping, but I would rather it have never run at all. By engaging in debate on the question, you give it validity. It’s best to deal with gatekeeping by not even acknowledging that the question is valid.
Every once in a while, someone suggests writing laws like code. Bills are pull requests. You can easily see diffs from previous versions. It’s an appealing idea.
But sometimes I think about how political structures resemble code. Specifically, the U.S. Constitution reminds me of most of the code I write: it’s mostly happy path and there’s not a lot of error checking. They both assume good actors all around.
Just as Madison et al did not consider that a presidential candidate might receive material support from a foreign power and that large portions of the Congress might choose to turn a blind eye to it, I don’t really think about how a bad actor might use code I write.
Of course, I mostly write code for my own use. And the Constitution isn’t workable if it covers great detail. But a little more exception handling and testing is probably good for both of us.
When working in a group, you may sometimes struggle to get the group won over to your way of thinking. It’s a challenge. Sometimes you can’t state your case in a compelling manner. Sometimes your idea is terrible. Sometimes the group just won’t listen. But there’s a shortcut you can use to give your opinion a head start: write it down.
Blank pages are scary. They contain infinite possibility. It turns out that infinity is a really big, daunting concept. People don’t like them. This makes the blank page your opportunity.
Undoubtedly, the team will edit your draft heavily. It may get to the point where nothing remains of your original work. That’s okay. By having your opinion be the starting point, you give it some extra weight. You’re framing the discussion. If you’re particularly sneaky, you can even go a little beyond your actual position so that when it gets edited more toward the “middle”, it lands where you wanted.
This isn’t a fool-proof method by any stretch of the imagination. But you’re giving your idea a little bit of a boost. Even if your position isn’t the one the group settles on, being willing to write that first draft sets you apart. It doesn’t particularly matter if it’s good or not, because it’s going to be revised and revised and revised. So do you yourself a favor and just write the damn thing.
I don’t remember how it crossed my field of view, but I recently read a blog post from the CEO of Carta. In it, he talks about their company culture and how new employees get introduced to it. Since I have had a few conversations on this general topic with my colleagues who are in charge of such things at my employer, I read it with great interest.
Until I got to the sports team analogy.
Most companies find role models in other companies (e.g. Facebook, Google, GE). They aspire to be like “Company X”. I propose an alternative model for Carta. We don’t model ourselves after companies. We model ourselves after professional sports teams. My question for you is, “What is the difference between a company and professional sports team?”
There are many similarities between Carta and a professional sports team. For starters, our entire company meets everyday at 8:30am to begin the day together. Everyone — engineering, sales, services, office management. Nobody is exempt. In sports, even the goalie, who may have a completely different practice schedule from the rest of the team, still meets at the same time to warm up.
Most people think it’s crazy that we make everyone be in the office at 8:30am every morning. We think it is crazy not to. The New England Patriots would never tell players, “Show up for practice when it is convenient.” If you want to be the best in the world at what you do, start every day together.
This is bad. It is so bad. What I read when I see this is “if you’re a parent, we don’t want you.” Or any other number of reasons why being in the office regularly at 8:30 might not work.
Now don’t misunderstand me: it’s important to be a reliable coworker. But the idea that the entire company needs to start the day together is ridiculously exclusionary. Sports teams practice together because they need to work closely together in split-second situations. They need to develop an almost telepathic understanding of what their teammates will do. They also get paid millions of dollars a year.
Your office manager does not get paid millions of dollars a year. The success of your company does not depend on the perfect, split-second timing of your lead developer and East Coast sales representative. You should develop team rapport and trust but in a way that makes sense for the work they do. Not exclusionary Valley Bro crap.
There are some really good ideas in the post: the full-day culture orientation, the idea of not taking too much capital in an attempt to grow as fast as possible, the idea that everyone contributes to customer success. But the shadow of the crappy sports analogy is deep enough to overwhelm the good parts.
I recently saw a tweet that infuriated me:
“We welcome our customers,” Best Buy training supposedly says, “not greet them.” First off, if you’re doing this, fuck you. This is silly word-lawyering for any job, but particularly for retail. They’re already relatively low-paid and high-bullshit, why are you making it worse?
But even apart from treating your employees like they’re people, there’s a business argument for this. Over-engineering customer service interactions makes them less serving of the customer. Empowering the employees to serve the customer leads to better service. And it turns out better service can help you keep your customers.
By coincidence, I had to deal with a couple of financial firms earlier this week. The first interaction boiled down to “welp, I can’t really do much for you. Go away.” The second, with Fidelity, made me feel like my problem was their problem, too, and it would get solved. Every time I’ve needed something from Fidelity, I’ve felt that way.
The same is true for T-Mobile. Even when it’s possibly not their problem, they do as much as they can to help me solve it. As a result, I’m still a T-Mobile customer, even though the coverage map isn’t as coverage-ful as I’d like. This is in no small part due to the quality of service I’ve received.
In both of these cases, the customer service representatives don’t feel like they’re mindlessly reading from a script. I get the sense that I’m talking to an actual person who wants to solve my problem, not close my case. They don’t seem to be judged on the difference between “greet” and “welcome”.
What have I been writing when I haven’t been writing here?
Stuff I wrote
Stuff I curated
Chris Siebenmann recently wrote a post about Golang where he said: “Go is Google’s language, not the community’s.” The community makes contributions — sometimes important ones — but does not set the direction. We frequently use “community project” to mean two separate ideas: a corporate-lead project that accept community input and a project (that may have corporate backing) lead by the community.
Neither one is particularly better or worse, so long as we’re honest about kind of project we’re running. Community-contributed projects are likely to drive away some contributors, who don’t feel like they have an ownership stake in the project. Chris mentions that Go’s governance has this effect on him. And that’s okay if you’re making that decision on your project intentionally.
Some community-contributed projects would probably welcome being community-led, or at least somewhere closer to that. But technical or governance barriers may inadvertently make it too difficult for would-be contributors to ramp up. This is one area where I don’t think GitHub’s position as the dominant code hosting platform gets enough credit. By having a single account and consistent interface across many unrelated projects, it becomes much easier for someone to progress from being a bug filer to making small contributions to becoming (if the project allows it) a key contributor.
A lot of people who work on open source software get paid to do so. Many others do not. And as we learned during the Heartbleed aftermath, sometimes the unpaid (or under-paid) projects are very important. Projects have changed their licenses (e.g. MongoDB, which is now not an open source project by the Open Source Initiative’s definition) in order to cut off large corporations that don’t pay for the free software.
There’s clearly a broad recognition that maintainers need to be paid in order to sustain the software ecosystem. So if you expect that people are happy with GitHub’s recent announcement of a GitHub Sponsors, you have clearly spent no time in open source software communities. The reaction has had a lot of “pay the maintainers! No, not like that!” which strikes me as being obnoxious and unhelpful.
GitHub Sponsors is not a perfect model. Bradley Kuhn and Karen Sandler of the Software Freedom Conservancy called it a “quick fix to sustainability“. That’s the most valid criticism. It turns out that money doesn’t solve everything. Throwing money at a project can sometimes add to the burden, not lessen it. Money adds a lot of messiness and overhead to manage it, especially if there’s not a legal entity behind the project. That’s where the services provided by fiscal sponsor organizations like Conservancy come in.
But throwing money at a problem can sometimes help it. Projects can opt in to accepting money, which means they can avoid the problems if they want. On the other hand, if they want to take in money, GitHub just made it pretty easy. The patronage model has worked well for artists, it could also work for coders.
The other big criticism that I’ll accept is that it puts the onus on individual sponsorships (indeed, that’s the only kind available at the moment), not on corporate:
Like with climate change or reducing plastic waste, the individual’s actions are insignificant compared to the effects of corporate action. But that doesn’t mean individual action is bad. If iterative development is good for software, then why not iterate on how we support the software? GitHub just reduced the friction of supporting open source developers significantly. Let’s start there and fix the system as we go.
FCC Chairman Ajit Pai announced his support of a proposed merger between T-Mobile and Sprint. It’s not often that Chairman Pai and I agree on anything, so I feel I should point out when it happens. T-Mobile and Sprint are the third and distant fourth place players in the U.S. cellular market. Combined they’d be second behind Verizon.
Normally, fewer players in a market means less competition. I think this may be the rare case where fewer players makes for more competition. Right now, T-Mobile competes on price, customer service (T-Mobile Tuesdays, anyone?), and speed (where you get coverage). Speaking from my experience as a T-Mobile customer, the service is top-notch, where it exists. And that’s where a merger might help. By combining resources, the larger T-Mobile can improve geographic coverage and perhaps give Verizon a run for the money when spectrum goes up for auction.
For all of T-Mobile CEO John Legere’s bravado, T-Mobile is basically yapping at the heels of Verizon and AT&T. Sprint, meanwhile, is destined to die at some point. Allowing it to merge with T-Mobile means that Verizon and AT&T don’t get to gobble up the carcass in bankruptcy auction. The Department of Justice disagrees, so it remains to be seen if the merger can complete. But I think it would give us three big players, instead of two big players and two smaller players. That sounds more competitive to me.
Full disclosure: I am a T-Mobile customer and shareholder.