Upcoming meetup in Sydney: open source, change in the digital age, developer docs, and you!

The Write the Docs AU community is holding a meetup in Sydney on Thursday, 21 February. 

If you have a view on technical documentation, you’re invited!

Date and time: Thursday, 21 February 2019, at 6pm – 7:30pm

Location: Google, 48 Pirrama Road, Pyrmont (map)

Sign up on Meetup.com

There’s pizza and the opportunity to chat with friends old and new. Then we’ll move quickly to the exciting lineup of talks:

Building awesome technical writers from open source communities

Speaker: Cameron Shorter

The secrets behind inspiring an open source software community to write awesome docs. A story about how we initially got it wrong before improving. (Spoiler – technical writers play a cornerstone role).

Cameron is a software developer, business analyst, open source community builder, and accidental technical writer.

Tech Writers as Agents of Change in the Digital Age

Speaker: Priya Varghese

As we race through the digital era, swiping away one app after another, there are numerous companies and organizations out there that haven’t yet strapped themselves in properly for the digital transformation roller coaster.

Priya Varghese (a technical writer) talks about how technical communicators can become agents of change (in a disguised double role), with the key skills, advantages and vantage points to successfully help their teams on board the digital transformation journey.

Getting started for developer documentation

A lightning talk.

Deepti Korwar, a technical writer, talks about the necessary skills and available resources for writers considering to move into developer documentation roles.

Lightning talk 2

This five-minute spot is open. Suspense! Someone may stand up and speak impromptu at the event.

See you there!

Applying for the Google Sydney tech writing role? Some hints from me

Google currently has an open role for a technical writer in the Sydney office. See the job posting. Here are a few thoughts, from me as a tech writer at Google in Sydney, on how you can prepare to apply for the role.

A note up front: These hints come from me personally, as a tech writer at Google. I’m not the hiring manager for the open role, and following these hints won’t assure you of a successful application.

The advertised role is for a technical writer in the software engineering area. Let’s dive straight in!

Resume, samples, writing exercises

For a tech writing application, the resume is super important. Treat your resume as the first writing sample you’ll submit to Google. Make sure it’s clear and consistent. For example, it doesn’t matter whether you use US, British, or Australian spelling, provided you stick to your choice throughout the document. The same applies to punctuation of bullet items—just be consistent. Avoid unnecessary capital letters, check your spelling… you know the drill.

If your resume shows the skills and experience that suit the role, Google will ask you to submit some writing samples and complete a set of writing exercises.

For the writing samples, make sure you send in the work that demonstrates sound tech writing principles. If you have any code that you’ve written and that you can link to from your resume (for example, on GitHub), that’d be useful too. Even if the code is something you put together while learning a programming language or experimenting with an API, that’s good.

You may be asked to complete some specific writing exercises. Take your time in completing the writing exercises. Apply your tech writing soft skills as well as standard tech writing principles. A good tip is to sleep on it before you submit the exercises. Come back the next day to take a fresh look at what you’ve written. Focus on the intended audience for each sample. Include comments noting any extra information you’d ask for if you were writing the docs in a real work environment.

Interviews

Once your first interview has been scheduled, you’ll be able to chat to the Google hiring representatives and they’ll give you plenty of information about the interview process.

Usually there are a number of interviews, some by phone and some in person. You’ll speak to people in different roles, which may include tech writers, engineers, developer advocates, managers, and more.

A good hint for the interviews themselves is to remember you’re a tech writer, with the skills of a tech writer, and those skills are not the same as those of an engineer. Your interviewers may be tech writers, engineers, or managers. So, ask questions during the interview as if you were interviewing an engineer or a product manager. Make it clear to them that that’s what you’re doing.

You can find more tips to help you prepare on the Google Careers site.

General preparation

During the leadup to the interviews and throughout the process, read widely to keep programming terminology and concepts on the tip of your tongue. Read as much as you can about web programming and any other aspects of programming that interest you. Explore the world of APIs in full—be aware of Android and iOS APIs, JavaScript APIs, etc, as well as REST APIs.

It’s a good idea to become familiar with Google developer products, docs and style, to show your interest in the role. Be aware of the Google Developer Docs Style Guide, browse the Google Developer Docs site and the Google Cloud docs.

Coding

People often ask about the coding requirements for a tech writing role at Google. It’s a vexed question, and you’ll receive different replies depending on the role. This section of the post takes up a lot of space—arguably too much in proportion to its importance—but I’d like to give the best hints possible.

For this role the expectation is that you can comment on things like consistent and meaningful names for methods and classes, good use of code comments, and other aspects of code readability. In an interview, you should be able to ask the interviewer questions about a piece of code, as you would if you were planning to document it.

The job description mentions a few programming languages. It’s a good idea to focus on one (I’d recommend Python if you don’t already have a favourite) and do some studying in the leadup to the interview process. In fact, when I applied I continued studying throughout the process to keep the concepts and skills in focus. Life is busy, and it’s easy for some things to drop down into the less-easily accessible areas of our brains! This Python course is a good one.

To the best of my knowledge, you shouldn’t have to solve a problem in code during the interview. At most, you may be asked to write pseudo code. I’ve heard various reports about whether you need to do whiteboarding of simple code during an interview. I think it depends on the interviewer. I did have to do some whiteboard coding in one of my interviews, and I totally messed it up because I was extremely nervous. I still got the job. I did much better on the conceptual questions (what is a class, what is inheritance, what does “closure” mean to you, and so on).

For this particular role, we’re looking for someone who’s willing and able to continue learning about software and code. It’s not necessary to have in-depth coding skills. If during an interview you’re asked to do some coding that’s beyond your current skills, fall back to discussing the key technical concepts involved and to interviewing the interviewer about the requirements and goals of the application / system.

My top hints

Be passionate about tech writing. Let the interviewers see that you enjoy the role of tech writer, and be ready to tell them why. If you’re active in the tech writing community, let the interviewers know that. Mention any opportunities you’ve had to mentor other tech writers or students.

Be yourself. 🙂

KubeCon Seattle 2018 – open source, docs, community

This week I attended the KubeCon conference in Seattle. The conference’s full name is KubeCon + CloudNativeCon North America 2018. It was huge, friendly, interesting, inspiring.

Most of the conferences I attend are tech writing conferences. This is the first time I’ve attended a highly “technical” software conference, and I wasn’t sure what to expect. Would all the sessions fly right over my head? Would the other attendees view me as an interloper? Would documentation feature at all? The answers are, “well yes some”, “no”, and “yes”!

KubeCon was huge. This year there were 8 000 attendees, which is eight times more than the last time the conference took place in Seattle, in 2016. It’s twice as many as last year, when the conference was in Austin, Texas

Part of the room in which the keynotes were held:

KubeCon revolves around Kubernetes, an open source system that helps people deploy and manage containerised applications. The Kubernetes website saw 1.8 million visitors last month. A keynote speaker, Liz Rice, remarked that these numbers make the Kubernetes website massively more popular than the Seattle Seahawks but less visited than Starbucks. What’s more, the Kubernetes readership has just started exceeding that of the Manchester United website!

A Kubeflow end-to-end workshop

I took part as teacher’s assistant (TA) for the Kubeflow end-to-end workshop, run by Michelle Casbon and Amy Unruh. Kubeflow is a framework that helps make it easier to deploy and manage machine learning systems. (I work on the Kubeflow docs.) The Kubeflow session at KubeCon took the form of a codelab which was rewarding in that it showcased some very cool technology in a graphical way, though, as is still the case with most machine learning systems, the workflow was somewhat complex. (This is something we’re working on.) I’m very pleased I was able to help many people get their apps up and running.

Awaiting the start of the Kubeflow workshop:

Notes on sessions related to open source docs and community

I blogged about some of the other sessions I attended – those related to docs and/or community:

Thanks

Thanks to the conference organisers, presenters, and attendees. I had fun, met good people, and learned a lot.

It was invigorating to attend an event where the technology and the community are thriving, growing, excited, and yes, just slightly chaotic. This year Kubernetes won the OSCON Most Impact award (OSCON = Open Source Convention). The word “community” is on everyone’s tongue, as much as the word “code”.

This is Seattle. It rained, but rain did not dampen our spirits.

Crossing from one conference building to the other in the Seattle rain:

Update on 19 December: KubeCon videos are available

The talks and other sessions are available on the Seattle ’18: KubeCon and CloudNativeCon playlist on YouTube.

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.

%d bloggers like this: