Sarah Maddox's Blog, page 7

Wikidata, open data, and interoperability

This week I’m attending a conference titled Collaborations Workshop 2019, run by the Software Sustainability Institute of the UK. The conference focuses on interoperability, documentation, training and sustainability. I’m blogging my notes from the talks I attend. All credit goes to the presenter, and all mistakes are my own.

Franziska Heine presented a keynote on Wikidata, a Wikimedia project that provides structured data to Wikipedia and other data sets. Franziska is Head of Software & Development at Wikimedia Deutschland.

Franziska’s talk was titled “Wikidata, Interoperability and the Future of Scientific Work“.

The Wikidata project

Franziska said she’s very excited to be here and talk about Wikidata, as it’s such a big part of what her team does. She cares about making Wikipedia, which started 20 years ago, into something that remains meaningful in the future.

Wikidata makes interwiki link semantics so that computers can understand the relationships between the pieces of data. When you ask Siri or Google Assistant a question, the answer comes from Wikidata. Franziska also showed us a map of the world with a data overlay sourced from Wikidata. (I can’t find a link to that specific map, alas.)

Wikidata has more than 20,000 active editors per month. That’s the highest number in the entire Wikimedia movement, surpassing even the number of edits of the English-language Wikipedia.

How Wikidata works

The core of Wikidata is a database of items. Each item describes a concept in the world. Each item has an ID number (“Q number”). Items also have descriptions and language information. In Wikipedia, the content for each language is completely separate. So, you can have the same topic in various languages, each with entirely different content. By contrast, in Wikidata all the languages are properties of the single data item. So, for example, each item has a description, and the description may be available in various languages.

Each item is also linked to all the various Wikipedia instances.

Each item has a number of statements (pieces of information), such as date of birth, place of birth, date of death, and so on. Each statement lists the sources of the information. It is of course possible that different sources may provide conflicting information about a particular statement. For example, there may be different opinions about the date of birth of a person.

Wikidata can be edited by people, but there are also bots that do the updates. The concepts within Wikidata are not built primarily for humans to navigate, but rather for machines to understand. For example, Wikidata is able to give Siri and Google Assistant information in ways that Wikipedia can’t.

But can humans look at the data?

Yes! You can use the Wikidata Query Service to access the data. To get started, grab an example query and then adapt it. The query language is SPARQL.

Franziska showed us some interesting query results:

The location of trees grown from seeds that have travelled around the moon.

Open data reduces friction in sharing and use of data

This week I’m attending a conference titled Collaborations Workshop 2019, run by the Software Sustainability Institute of the UK. The conference focuses on interoperability, documentation, training, and sustainability. I’m planning to post a blog or two about the talks I attend. All credit goes to the presenter, and all mistakes are my own.

I’m very much looking forward to the conference. The audience is slightly different from the developer-focused and tech-writer-focused gatherings that I see more often. At this conference, attendees are a lively mix of researchers, engineers, educators, and others. The goal of the Software Sustainability Institute is to cultivate and improve research software.

Better software, better research [reference]

Opening keynote by Catherine Stihler

Catherine Stihler is the Chief Executive Officer of Open Knowledge International. She presented the opening keynote of the conference.

Catherine’s talk was titled “Transporting data more easily with Frictionless Data“.

Frictionless Data

Frictionless Data is one of the primary initiatives of Open Knowledge International. The website offers this description:

Frictionless Data is about removing the friction in working with data through the creation of tools, standards, and best practices for publishing data using the Data Package standard, a containerization format for any kind of data.

These are the challenges the Frictionless Data initiative addresses:

Legal barriers
Data quality
Interoperability
Hard to find
Tool integration

A goal of Frictionless Data is to provide a common packaging format that can hold many different types of data. So people can understand and use your data as easily as possible. Catherine used the metaphor of shipping containers to talk about data packages.

Publishers can create the data packages, and
consumers can plug the data packages into their systems.

There’s more information at the frictionlessdata.io website, including the Frictionless Data specifications and software (apps, integrations, libraries, and platforms).

As well as revolutionising how data is shared and used, the Frictionless Data initiative aims to massively improve data quality.

Open data

Open Knowledge International is a strong supporter of open data. They’re currently advocating against the EU copyright law, specifically Article 13, which many fear will result in the implementation of upload filters to ensure that the big content aggregation companies don’t fall foul of the law.

Catherine spoke passionately about the issues around political advertising on social media, the Responsible Data initiative, and the Open Definition which sets out principles defining openness in relation to data and content.

Catherine says the key challenge right now is that we could go down a closed, proprietary route where only those who have money will have access to knowledge. We need to win the debate about the importance of an open society and open and free knowledge.

Thank you Catherine for a spirited introduction to Open Knowledge International and its work.

Illustrating the multifaceted role of a tech writer

After a few conversations with various people, I decided that it may be useful to have an illustration of the multifaceted role of a tech writer. In particular, many of our stakeholders (product teams, engineering teams, marketing teams, etc) may not know all the ins and outs of what we do. A handy illustration may help conversations with product teams and other stakeholders.

Many people see our role as being focused on documenting the features of a product:

[image error]

Here’s an illustration of the tech writing role, de-emphasizing the feature docs part of the role:

[image error]

The many aspects of a tech writer’s role:

Gather the information required to develop the docs. Some ways to gather information: interview engineers, product managers, etc; read the code; read the product requirements document and other specifications; experiment with the product.
Analyse and define the audience.
Analyse the most common tasks and workflows of the target users.
Design the structure of the docs as a whole (information architecture).
Own the user experience (UX) of the docs: consistency; findability, readability, accessibility.
Ensure consistency with the product user interface (UI).
Ensure cross-product consistency, that is, consistency with the docs of related products: tone, terminology, coverage.
Review doc updates from other technical writers, engineers, and community contributors.
Stand up for the customer and give UX advice, as the first-time user of the product.
Create conceptual guides that explain the product at a high level, for new starters, and that explain the principles and details behind the product design and functionality, for people who want a deep dive into a particular technology.
Create getting-started guides covering the primary product features.
Create end-to-end tutorials, each covering a use case that involves multiple features.

Some technical writers have an even broader purview, depending on the team and the doc set they’re working with. For example, if the doc set is hosted on a self-managed website as opposed to a corporate website with shared infrastructure, the tech writer often takes on website design and management tasks. Small teams may not have software engineers available to create code samples, and so the tech writer creates those too. Open source docs in particular bring additional responsibilities.

Here are some of the additional tasks a tech writer may take on:

Develop illustrative code samples to include in the documentation.
Develop training material.
Produce videos, either as training material or as illustrative material to supplement or even replace the documentation.
Own the design and infrastructure of the documentation website: look and feel (theme), site search, version control, navigation aids, etc.
For open source products, educate and encourage the community to contribute to the docs.
Manage the repository that holds the documentation source files.

FYI, I based the above diagram on one that’s often used in presentations about machine learning (ML) to show the relatively small part of the ML workflow that’s devoted to actually writing the ML code. The original ML diagram is in this paper.

What do you think?

Does this diagram present an interesting way of starting a conversation about the role of a tech writer? I’d love to hear your thoughts and ideas!

How open source organizations can prepare for Season of Docs

Last week Google announced a new program, Season of Docs (g.co/seasonofdocs). The program provides a framework for technical writers and open source organizations to work together on a specific documentation project chosen by the open source organization and the tech writer concerned. From April 2, interested open source organizations can start applying for this year’s Season of Docs. Exciting news indeed! But what happens before April 2? I decided to blog about some ways you can get started with Season of Docs right now.

Open source organizations can start planning the documentation projects they’d like help with, and letting technical writers know about those projects. Get the conversation going, and build up excitement amongst your open source community and amongst the technical writing community.

The first step is to think about a good project or projects that a technical writer can help you with. The Season of Docs website provides some generic ideas for doc projects. You should to craft a specific project or two, based on the actual doc needs of your project. Include links to the relevant docs or other resources within your open source repository or on your website. I’d recommend that you propose a a few different project types, because different tasks may be of interest to different tech writers. For example, you could offer one project to refactor your existing docs, another to create a specific tutorial, and so on.

Your goal is to attract tech writers by making them feel comfortable about approaching your organization and excited about what they can achieve in collaboration with your mentors during Season of Docs.

It’s a good idea to find out who in your community wants to be a mentor. The mentors don’t need to be tech writers. There’s help about the mentors’ role on the Season of Docs website too.

When you’ve gathered some project ideas, blog about the fact that your organization is putting forward an application to participate in Season of Docs. Use the blog post to tell tech writers about your ideas and ask for input. You don’t need to wait for applications to open. You can get a head start by kicking off the discussion now.

Use the tag #SeasonOfDocs when promoting your ideas on social media. To include the tech writing and open source communities, add #WriteTheDocs, #techcomm, #TechnicalWriting, and #OpenSource.

Season of Docs fostering open source collaboration with tech writers

Exciting news: Google Open Source has announced a new program called Season of Docs. I’m excited because the goals of this program reflect two passions of mine: to help technical writers get started in the world of open source software, and to help open source projects build great documentation. I’m also excited because I’m on the program development team for Season of Docs.

[image error]Season of Docs sets up a framework for open source projects to invite technical writers to work on the projects’ documentation for a few months.

Technical writers bring their documentation expertise to the open source project of their choice. In return, mentors from the open source organization help the technical writer gain an understanding of their open source community, processes, tools, and code.

A golden collaboration

When technical writers contribute to open source projects, both parties benefit. The open source project gains good documentation and improved contribution procedures. The technical writer gains experience in open source software, developer-focused products, new tools, and the ways in which open source communities work. A golden collaboration.

Open source is great. Some of the world’s most-used software is open source: the Linux operating system, Firefox web browser, LibreOffice, Apache web server, to name but a few well-known brands. Large companies like Microsoft, Google, Red Hat, and IBM contribute to, as well as use, open source code.

Open source ideology is great too. People share code in public repositories, collaborate on making the code better, invite others to join their communities… yet, all too often, people expect those newcomers to understand the product, the code, and the community’s values with very little good documentation.

Why the dearth of good docs? It’s clear from GitHub’s Open Source Survey that open source organizations know the value of good documentation, so why are there so many gaps? Because writing documentation is hard.

But wait… there are people who know how to do it well!

Many technical writers are keen to gain experience in developer-focused products such as APIs, SDKs, and various programming languages and tools. Technical writers look for opportunities to explore cloud computing, machine learning, hardware, and more.

When a technical writer wants to expand their resume or look for a new role, the advice is sometimes to build a portfolio by contributing to open source. But that’s not easy. There are so many open source projects out there. Where do you start? How can you be sure your contributions will be useful to the open source project? Who can help you understand the contribution procedures, the product, and the code?

Season of Docs gives technical writers and open source projects the opportunity to work together within a structured program.

Let’s go build great open source docs!

How does Season of Docs work?

First up, open source organizations apply to participate in Season of Docs. The list of accepted organizations is then published on the Season of Docs website, along with the ideas each organization has proposed for technical writing projects.

Then technical writers explore the list of participating open source organizations and their project ideas.

As a technical writer, you can decide which open source project you’d like to work with. It’s a good idea to get in touch with the open source organization to chat about their requirements and your own ideas. You can contact more than one organization if you like.

When you’re ready, you submit your application to participate in Season of Docs, including your project proposal and the name of the open source organization you’re interested in. You can submit more than one project proposal, but only one will be accepted.

If your technical writing project is accepted for Season of Docs, then you as a technical writer will work with your chosen open source organization for a few months (starting in September 2019) to complete your project. You work closely with your open source mentor for the duration of the program, to ensure successful completion of your project.

At the close of the program, the successfully-completed projects are published on the Season of Docs website and on the Google Open Source Blog.

When can you start?

Open source organizations can start applying to participate in Season of Docs from April 2, 2019, and the website will show the list of participating organizations on April 30. Technical writers then have the opportunity to examine the list of participating open source organizations and explore the project ideas proposed by the organizations.

Technical writers can start applying to participate in Season of Docs from May 29, 2019.

The Season of Docs timeline shows the key dates and what happens in each phase of the program.

Want to learn more?

Take a look at the Season of Docs announcement on the Google Open Source Blog, or dive into the guides on the Season of Docs website at g.co/seasonofdocs. Join the mailing list at season-of-docs-announce to stay informed about when applications open and other important program events.

A lightning talk on doc sprints

At the upcoming Collaborations Workshop 2019, run by the Software Sustainability Institute UK, I’ll be presenting a lightning talk on doc sprints. One slide, three minutes. Wow, that’s a short time for a big topic.

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:

[image error]

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:

[image error]

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:

The art of documentation for open source projects, notes on a talk by Ben Hall
Open source, community, development, notes on a talk by Craig McLuckie
Fostering diversity in open source projects, notes on a panel discussion by Orna Berryman, Jasmine Jaksic, Lin Sun, and Limin Wang
How to bootstrap an open source project, notes on a talk by Peter MacKinnon

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:

[image error]

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.