Author Archives: Sarah Maddox

How to bootstrap an open source project – 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.

Peter MacKinnon talked about bootstrapping Kubeflow, an open source project that aims to provide stability, composability, and portability for machine learning workflows. His talk was entitled “Eco-Friendly ML: How the Kubeflow Ecosystem Bootstrapped Itself“. Peter discussed how an open source project can rapidly achieve its potential by working with other projects, and how those inter-project collaborations enrich the entire Kubernetes community.

About Kubeflow

Peter gave a quick overview of Kubeflow, and how it helps people develop a machine learning (ML) pipeline. The goal of the Kubeflow project is to enable machine learning for everyone. This is a difficult problem to solve.

The Kubeflow team started with a mission statement: The ML pipeline should be portable (from bare metal to cloud), scalable, and composable (a micro-service architecture).

Then the team decided on a baseline platform – Kubernetes fits the bill. From this decision came the goal:

Anywhere you can run Kubernetes, you can run Kubeflow.

Open is key

To bootstrap an open source project, get in touch with other communities and see what they’re working on and whether their goals align with yours. Look at blogs, forums, conferences. Talk to people, in person, at conferences, on Slack. Get involved. Go deeper on GitHub – raise issues, contribute to your chosen projects by raising pull requests.

Observe the open source etiquette. Get your git technique right, help other people with those techniques, and respect the community of the projects you’ve chosen.

The Kubeflow tech

Peter talked us through some of the technical projects that Kubeflow has integrated with. The examples he gave were ksonnet, Ambassador, Argo, JupyterHub, Kaggle, RAPIDS AI at NVIDIA, TensorFlow, Pachyderm, Arrikto, and SeldonIO. You can see some of the details in the Kubeflow docs and on GitHub.

The Kubeflow team holds open conversations with these related projects, so that they can work together to develop solutions that are advantageous to all.

What makes a good community?

Kubeflow has a strong code of conduct, based on the Cloud Native Computing Foundation (CNCF) code, with the goal of ensuring a harassment-free experience for everyone. They have documented community standards and conflict resolution protocols, and they work with other communities in their ecosystem to support the same standards.

The power of open source

Peter says Kubeflow is a great community. It’s only a year old, and he has a lot of fun there. Everyone wins when communities collaborate, and Peter encourage contributions and ideas from other communities. Open source communities, when they work well, give contributors a sense of empowerment and achievement beyond what they do in their day job.

Thanks

Thanks Peter for an engaging look at a new open source community.

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. 🙂

Here’s what Ben talked about:

  • Where docs fit into the user journey
  • How docs support users
  • Examples and inspiration for docs

These are the types of people who use the docs: potential users (people who’ve heard about the project and are interested in starting to use it), implementers, maintainers, and contributors.

There are a few myths about docs, including that no-one reads, and definitely no-one wants to write docs, yet the docs must exist. Ben says to address this type of thinking, we need to analyse the types of documentation people need, what they want to read. For example, avoid large blocks of text. No-one wants to read them, and writing them is hard.

Docs for new users

Consider how people approach the docs:

  • The commitment pattern is very rare – this is where the reader sits down and reads the entire text from top to bottom.
  • The layer-cake pattern is more common – people scan for headings and for things that are interesting to them.
  • The spotted pattern is where people look for specific items e.g. a specific guide. This is also common, especially when people have used the product before.

Someone starting with the project may ask themselves: Does this project solve my problem, and will it help me with my career? Note that the README will probably be the first doc a person reads. So pay attention to it, and make sure it gives people a good overview and signposts to where to go next.

Avoid saying something is simple, or tell them to just deploy using x. Rather, showcase the project in the smallest amount of time, to help them decide whether the project is right for them. Examples are the best way of doing this. (Short videos and GIFs are often used too, but people have to download and watch them, which may be discouraging.)

Kubernetes, for example, has an interactive element in the website which gives people a feel for the project. Stripe found a significant advantage when they included interactive snippets in their website. Realistic blocks of code where you can see the core aspects of the product working.

A good tip is to include snippets of code in the docs, and link directly to GitHub for people who want to see the rest of the code.

We also need to make docs inclusive. Take care with the examples we use. Respect the fact that not everyone’s first language is English. Don’t use words like “it’s simple” or “just do this”, because for many people it’s not simple. Avoid making the user feel bad. The problem is ours, we need to make the software as simple as possible, and the docs should acknowledge that.

Docs for an active user

Active users of the project have needs that differ from those of new starters. They want to solve other problems, or find a solution for something that’s broken.

We need to focus on how people can find what they’re looking for. Discoverability in the docs. Ben gave the example of the Twilio docs, which ask readers a few questions before deciding where to take them.

If something is broken, consider the user’s emotional state at this time. They probably don’t want to read a lot of text at this time. StackOverflow and GitHub Issues have become key resources for this type of use case. When writing our docs, we need to acknowledge these resources. For example, point people to an issue and make sure the issue is informative.

Docs for community contributors

We must make sure there are good contributor guidelines. Make sure people feel safe, by including a code of conduct. Include a licence so people know the terms under which they’re contributing.

See the Kubernetes and Microsoft Azure docs for examples of great contribution guides.

Consider running a doc sprint where contributors can come and talk to project maintainers about becoming a maintainer themselves. Also working groups and contributor summits have huge impacts on showing people how they can improve their contributions to projects.

Three key points from Ben

Developers experiment. The docs should support this mindset.

Users get into trouble. Make sure we provide doc types that support the fact that people encounter problems.

We should encourage contributions. Not only the code base should be open source, but also the documentation.

In closing

From Ben: Having amazing documentation becomes your key differentiator.

From me: Thanks for a great talk, Ben, and +1 to fostering amazing docs for amazing open source projects.

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. 🙂

Approximately 100 people attended Write the Docs AU this year. Attendees came from Australia, the APAC region, and around the world. The following photo is from the Write the Docs photo set on Flickr:

Talks, workshops, and unconference sessions

The talks included:

  • Lana Brindley: Facebook, Dynamite, Uber, Bombs, and You
  • Mike Hamilton: Responsive Content – Presenting Your information On Any Device
  • Kristine Sihto: The Art of Consistency – Creating an inhouse style guide
  • Abhay Chokshi: UX writing – Let your product speak
  • Alexandra Perkins: Making Yourself Redundant on Day One – Internal documentation to teach the next hire what you’ve learned
  • Matthew Borden: Good Code, Bad Code & Code Review
  • Nicola Nye: The subtle art of interrogation
  • Daniel Stevens: Creating experiences with information!
  • Laura Bailey: Backseat Content Strategy
  • Mathew Patterson: Power up your support team to create better documentation

In addition to the presentations, we heard a number of informative, entertaining lightning talks. People could choose to attend one or more workshops and run or participate in a few thought-provoking unconference sessions.

These were the workshops:

  • Sarah Maddox: Tech Writing 101
  • Sara Marek: Let’s create a Style Guide!
  • Jessica Parsons: Static Site Generators, What, Why and How

Tech Writing 101 workshop

Around 50 people attended the Tech Writing 101 workshop, which I ran with the able help of Eric Gilmore.

This tech writing stuff is hard. But fun!

Tech Writing 101 is a two-hour workshop on the principles and techniques of technical writing. It leads the participants through a series of pair-work exercises to improve the clarity, readability, and effectiveness of their writing. You can read more about the workshop on the Write the Docs AU page.

By the end of the session, participants also think differently about toothbrushes.

The workshop pre-reading is available in LisaFC’s GitHub repo. A number of the workshop attendees let me know that they plan to introduce that pre-reading to their colleagues, as it’s a great introduction to the patterns of clear writing.

Photos and videos

Photos are in the Write the Docs photo set on Flickr. Videos of the presentations are in the Write the Docs AU playlist on YouTube.

Tweets and write-ups

Read the tweets at #WriteTheDocsAU. Here’s one of them from Nicola Nye:

Have you written a report on the conference, or come across someone else’s writeup? Let me know by adding a comment to this page or tweeting @sarahmaddox!

My takeaway from the conference

So many people who’re passionate about docs! It was a privilege chatting to engineers, UX designers and writers, and marketing folks, as well as other technical communicators. Thanks to everyone for a great conference!

 

%d bloggers like this: