Sarah Maddox's Blog, page 8

Open source, community, development – talk at KubeCon

This week I’m attending the KubeCon conference in Seattle. The conference’s full name is KubeCon + CloudNativeCon North America 2018. I’m taking notes from some of the sessions I attend. Any mistakes in these notes are my own, and all credit goes to the presenters.

Craig McLuckie, one of the Kubernetes founders, talked about how the Kubernetes project approached the community at the start of the project, and how that approach has shaped the future and success of the project.

From Craig:

“If it can be open sourced, it should…”

If you want to build a widely-accepted infrastructure technology, it has to be open sourced.

Open community from the start

Open source is important, but just as important is open community. Craig talked about how well Docker succeeded with this philosophy of focusing on the community, and how the Kubernetes team decided to follow the same philosophy. At the beginning, the team didn’t know exactly how to do this, though they had some ideas. They spent a lot of time thinking about how to build a magic community. The Kubernetes team were fortunate in that the team “clicked” – they worked very well together.

RedHat, Google, CoreOS all brought a lot of DNA in an open manner. The original group didn’t try to hold on to power. They realised that this wouldn’t scale, and they created the structures that would enable them to step back. Craig sees this as remarkable – he hasn’t seen it anywhere else.

Code and design in the open

Ship early and iterate quickly. This is like presenting an open design philosophy in code. Don’t worry about losing secrets to competitors. Iterate quickly and share the design and results with your customers. Share the roadmap in the open too. Your competitors will work with you.

What is the role of the foundation, CNCF?

It’s vendor neutral, provides structure, creates resources. But there’s another critical function: the foundation is a referee. It creates an environment where the end users can watch the creators and report any problems. The End User Community represents the people who have to live with the decisions of the rest of the foundation.

Balancing the pros and cons of open source

Open sourcing a project brings you adoption and engagement, but has disadvantages too. You lose some control and velocity, and gain some operating overhead. It’s always a matter of weighing adoption on the one side against the vectors on the other side, particularly if you want to commercialise the product.

If you develop something in a closed environment and surprise people when you launch it, be aware that people may surprise you in turn. If you develop in the open, you get useful feedback.

Marketing a launch

Don’t you lose a promotion and advertising opportunity if you develop at a slow burn? Not necessarily. There’s an advantage to a long buildup of news too.

Practical tips on how to design in the open

This was a question from the audience.

A friend of Craig’s, Evan from Knative, contributed to these points. The Knative team started thinking about Knative about six months before making the announcement. They wanted something to show rather than coming in with an open slate and asking the highly-opinionated community for comments. The team thought about who they wanted to bring on board as partners. They came up with RedHat who had similar offerings in OpenShift and Cloud Foundry. For the first 5-6 months, most of the development was done by Google, although there were other contributors too.

Consider another example, Istio, who threw the gates open very early, and that slowed things down at the beginning.

For small projects, on the other hand, it’s unlikely you’ll be deluged with ideas and contributors. So in that case, it’s a good idea to talk about it in the open and engage interest.

Having a roadmap and knowing what you want to do is very important.

When in doubt, remember that it’s better to ask for forgiveness than for permission.

Conduct experiments. Try things in low volume first. Stop when something isn’t working.

Thanks

Thanks to Craig for an interesting look at the philosophy of open source community.

The art of documentation for open source projects – talk at KubeCon

This week I’m attending the KubeCon conference in Seattle. The conference’s full name is KubeCon + CloudNativeCon North America 2018. I’m taking notes from some of the sessions I attend. Any mistakes in these notes are my own, and all credit goes to the presenters.

Ben Hall‘s talk was about how important documentation is to open source projects, and the changes communities can make to improve their documentation.

This statement from Ben’s introduction rings true with me:

While many open source projects have amazing code bases, the documentation is letting them down and as a result they are losing influence and opportunities for adoption and feedback.

I’ve worked on the docs for a few open source projects, and it’s hard.

Fostering diversity in open source projects – panel discussion at KubeCon

This week I’m attending the KubeCon conference in Seattle. The conference’s full name is KubeCon + CloudNativeCon North America 2018. I’m taking notes from some of the sessions I attend. Any mistakes in these notes are my own, and all credit goes to the presenters and to the audience who contributed ideas during the session.

Orna Berryman moderated a panel discussion titled “Growing Diversity in Open Source Projects”.  The speakers were Jasmine Jaksic, Lin Sun, and Limin Wang. The goal was to focus on how we can increase the number of people with different backgrounds, skill sets and experience working on open source projects.

The statistics for  the number of women in open source communities are around 3-5%. Orna put a question to the panel about why this may be the case. This compares to 20-30% in tech companies. One reason may be that there’s no regulation of bad behaviour in open source, such as instituting a code of conduct. More than 40 000 projects have already adopted one, many of them based on Contributor Covenant.

Another way to tackle the lack of diversity is to say something. Often, if someone addresses a problem immediately, the perpetrator will stop offending.

Imposter syndrome afflicts people starting on an open source project. There are a few ways to tackle imposter syndrome. Label issues with “help wanted”, or some way of indicating that an issue is a good place for a starter to contribute. Also provide mentoring for new starters, and recognise their work.

Communicating remotely can be intimidating. It’s hard to share your thoughts, and sometimes your thoughts are so different from the rest of the community that the community doesn’t appreciate them. (No-one +1s your comment.)

Travel is hard for some contributors, especially those who have young children. This makes it difficult to travel to conferences.

A question from the floor: what about governance? We can’t rely on an honour system. A code of conduct can’t do everything. We need to have governance over the community. The open source projects need to ensure there are members who monitor the behaviour within the community, and to take responsibility for that behaviour. Large organizations, such as the Linux community, should encourage this type of monitoring. The responsibility also belongs to every person in the community. Step in if you see bad behaviour happening.

People hesitate to join communities where they don’t see people who they can identify with. So communities should keep diversity front and centre.

Contributing to the community should be seen as of equal importance as contributing to the code. No matter how valuable someone’s code contribution, or how large their following, we should follow up on any bad behaviour by that individual.

Question from the audience: Is there a community where we can send people who need to create contacts? There are mentorship programs, such as Google Summer of Code for students. Opensourcediversity.org has a number of projects where you can sign up. There’s also outreachy.org for students who want to enter the open source community. and which focuses on diversity. If such programs can pay people, or provide childcare, this will make things easier for people with young children.

From the point of view of hiring new employees, open source contributions are viewed as more important than an internship. Employers should encourage people to work on open source projects, which are equally valuable to their CVs.

From me: Thanks to the panel for an interesting discussion. The points above should be useful especially for new open source projects, as well as for open source contributors.

Report from Write the Docs Australia conference

Last week I attended Write the Docs Australia 2018 in Melbourne. Around 100 documentarians gathered to discuss words, code, style, and other essentials relating to technical documentation. There was plenty of food and fun too.

“What’s a documentarian,” you may be wondering? In Write the Docs parlance, a documentarian is someone who cares about documentation. Documentarians include technical writers and communicators, as you’d expect, but also UX writers, software engineers, marketing content writers, and more. If you think docs are a Good Thing, you’re in.

Shutting down Tech Comm on a Map

Hallo folks, I’ve decided to take down Tech Comm on a Map—this means I’ll remove the web page and unpublish the Android app. The web page will remain available until the end of November, to give people time to fix up any pages that are using it. The Android app will remain installed on your device if you’ve previously installed it, but it won’t be available for new installations.

Why am I taking them down? I don’t have bandwidth to look after them any more. The web app is suffering from a technical problem that I can’t fix, despite quite a bit of effort. On the Android side, I don’t currently use Android technology, and it therefore takes quite a bit of effort to get back into the swing of things each time I need to make a change to the app.

The usage stats for the apps are reasonable, but not huge. The web page gets a max of 50 visitors per day, measured over the last 6 months. There are 27 active installations of the Android app.

I’ll leave the code available in GitHub (web app, Android app) at least for a while, for those people who want to try it out.

Thank you to everyone who has contributed data and code to this project! It’s been a rewarding experience developing the apps and working with contributors to the code and the data.

If my taking down the apps will cause you any trouble, please do let me know.

 

 

What is a quickstart to you?

When someone asks you to create a quickstart guide, what do you envisage? More importantly, what does the requester envisage, and what do your readers expect from such a doc? Is a quickstart the same thing as a getting-started guide? Are you all starting on the same page?

More on open source and technical writing

A few weeks ago I wrote a post about how technical writers can help open source contributors get started, and in so doing ramp up our own contributions to open source projects. A colleague has now pointed me to another great post on a related theme: Documentation as a gateway to open source, by James Turnbull.

My post focuses on the complexity of the open source world, which makes it difficult for anyone to get started, even to make a small fix to the source code or the docs. As technical writers, we can help people jump at least the initial hurdles. We can add docs that describe how to complete any relevant licence agreement, edit a code file or a doc page,  send an update for review, and eventually submit the update to the repository. In documenting the process, we become our own test subjects, as we need to go through that very process in order to document it. Sound familiar? It’s what we do best.

James Turnbull’s post takes things further. He describes how to:

Find a project that you can contribute to.
Consider the etiquette of the open source community that you’ve chosen, before jumping in and making a contribution.
Decide what type of edits to make. Both James and I describe READMEs as a good place to start. James goes on to examine strings, errors, and commands, and a few other file types too.

If you’re interested in open source, I recommend James’s post. It’s a good read.

Invitation to a Tech Writing 101 workshop, Melbourne, November

Are you a software engineer wanting to learn the patterns of technical writing? Or a technical writer wanting to refresh the ABCs of our craft? Or someone who loves debating and exercising good writing styles? Join us for a Tech Writing 101 workshop in Melbourne, Australia, on Thursday, 15th November.

The workshop is part of the Write the Docs AU conference, and the cost of the workshop is included in the conference registration.

Quick reference

Workshop name: Tech Writing 101

Date & Time: Thursday, 15th November 2018, 2.30pm – 4.30pm

Location: Library at the Dock, 107 Victoria Harbour Promenade, Melbourne, Australia

Signup: Register for the Write the Docs AU conference

Prework and what to bring

Before attending the workshop, you need to do a small amount of pre-reading (about half an hour).

This is where you discover that tech writing patterns are interesting and fun.

On the day of the workshop, bring a laptop with a text editor and an internet (WiFi) connection to do the exercises.

Workshop overview

The workshop leads you through a series of exercises to improve the clarity, readability, and effectiveness of your writing. You’ll work in pairs, learning from an experienced Google technical writer (me) and from each other.

Topics include the importance of knowing your audience; what can go wrong when you use passive voice; how to avoid getting tangled up in long sentences and disorganised paragraphs; how lists have taken over the world.

By the end of the session you’ll also think differently about toothbrushes.

During the workshop, you’ll apply the principles you’ve read in the prework. We’ve found this method of learning is highly effective. And it’s just plain fun. The workshop has been run at SREcon in Europe 2017 and at SREcon in the US in 2018, where it was very well received. People said they came away with useful skills and cleaner teeth.

Who’s welcome

The intended audience for the workshop is people who’re interested in learning how to write efficiently and effectively. That includes software developers, support engineers, UX specialists, product managers, technical writers, editors – well, really, everyone who needs to write technical content.

I hope to see you there!

Instead of a picture of a toothbrush (as that’d be a spoiler) here are some patterns from a recent walk in the bush:

[image error]

Two Australian tech writing conferences just around the corner

Are you in or near Australia in October and November? Then you’re in for a treat. We have two technical writing conferences in a row, within a stone’s throw of each other. Well, for some definition of “stone’s throw”, anyway.

Discovered the Issue Mover for GitHub and it’s super cool

This app makes it easy for me to move GitHub issues from one repository to another within the same GitHub org. I’ve just used it for the first time. It’s a real time saver. And it’s pretty too, especially if you’re fond of ladybirds.

The Issue Mover for GitHub:

UI that you can use to move issues
Code and project details on GitHub

What problem does the app solve? Let’s say you belong to an organisation on GitHub with a number of repositories. The number of repos has grown over the months and years, as it inevitably does. As a result, you frequently find yourself needing to move issues from one repo to another. It’s time-consuming to do that by hand. You need to copy across all the content of and comments from each issue, reassign each issue to the relevant contributor, add back all the labels, and finally close the original issue with a note saying that it’s moved.

I’ve jotted down some example use cases. I’m pretty sure you’ll have others in mind too:

Docs: Let’s say, in the earlier days of your project people were adding the doc issues to the code repo. But now you have a website, with its own code and its own repo. So, you want to move the open doc issues from the code repo to the website repo. This is the situation I found myself in. The Issue Mover worked like a charm.

Community: At first, all your community-related requests were lumped together with doc issues. But now you have a large community that’s creating procedures and tools of its own. You create a shiny new community repo and you want to move the relevant issues into it.

Software components: Your app/framework is expanding rapidly, and it makes sense to split off separate code repos for some of the larger, less tightly-coupled components. Of course, the relevant issues should go along for the ride.

General and ongoing: People keep putting issues into the wrong repo!