Author Archives: Sarah Maddox

Helping open-source contributors get started

Open-source software (OSS) is a big thing, and becoming ever bigger. Open source gives people the opportunity to contribute to large-scale projects, and it gives those projects the opportunity to gather expertise from the community of experts rather than being limited to employees of any one organisation. The documentation in an open-source project is arguably as important as the software. But it’s often hard for would-be contributors to know where to get started. That’s true for people wanting to contribute to the docs as well as the software. Here’s where we tech writers can help!

One of the biggest hurdles I’ve found as a would-be contributor is that I need to figure out so many peripheral frameworks and tools before I can even think about contributing to the core software or doc that I’m aiming for.

Framework upon framework

I’ve had this experience a couple of times recently. To make one simple change, I need to learn three or four frameworks/languages/tools. In the docs world, these frameworks and tools include Markdown, Django, Read the Docs, Hugo, Netlify, GitHub Pages, and so on. And then there’s git and GitHub… you get the picture.

It’s not even as if you have to learn a framework for each new project. Often the frameworks are stacked on top of each other, and you have to know them all just to make a simple commit to a project. For example, for doc updates a fairly common set includes Markdown, Git, GitHub, Hugo, and Netlify.

Engineers have their own frameworks to learn. On the web side, these may include Angular, Node.js, React, and so on. In the world of containerisation, there’s Docker and Kubernetes. And so on. Wherever you look, you find multiple frameworks piling one on top of the other. These frameworks add flexibility and agility to the software systems, but they also add complexity to the stack of concepts people need to absorb and the tools people need to manipulate.

Tech writer speaking: who’s my audience?

In this world of proliferating frameworks, what can we assume our readers know? The readers in this case are engineers and others who want to contribute to an open-source project. That means they want to make a change in a repository, test that change, and submit it for approval. This is true for the docs too: If a change is anything more than trivial, contributors need to test or preview it before submitting a pull request.

I think we can assume our readers have indepth technical knowledge of one or more languages or tools, but it’s unlikely they have indepth knowledge (or even any knowledge) of all the tools they need to do the job. And so, they come to the docs for help.

Too often, people have to go read the entire Internet just so that they understand how to make a simple change in a project.

As tech writers, this is where we can shine

We can give these tech-savvy people the information they to get started, and point them to more in-depth guides when they need them.

In short, we can show people:

  • The tools our particular project uses.
  • A basic workflow for making a change, including step-by-step instructions for the minimal operation of each tool.
  • Where they can find indepth information about each tool if they need it.

If you’ve recently made a change in an OSS project, or are planning to do so, jot down the steps you needed to take. They’re likely to be what everyone else needs to do too. If the project’s README file didn’t contain enough information to help you, submit a pull request that updates the README based on your experiences.

Even if you don’t have a particular change to make, take a look at the README or contributor’s guide for an OSS project that catches your eye. Does it tell you enough to get started? Would you be able to make a change to the contributor’s guide itself, by reading what’s in it? If not, consider updating the guide and using that experience to compile the steps as you go. It’s a great way to get some OSS contributions in your portfolio.

Examples of contributor guides / READMEs

These are a couple of OSS contributor guides I’ve updated recently:

Other examples:

  • The Kubernetes project has a nice README. I like the way it starts with a welcome!

Doc fixits and content strategy at Write the Docs Sydney on Tuesday

The next Write the Docs meetup in Sydney is just around the corner:

Sydney: Content strategy and doc fixits

Tuesday, Jul 3, 2018, 6:00 PM

341 George St, Sydney NSW 2000 Sydney, AU

28 Documentarians Attending

Join us to chat about docs – why they’re a Good Thing and how to make them even better. Tech writers, engineers, editors, product managers, more – if you’re interested in docs, you’re welcome. —————— Presenter 1: Michalina Ziemba **Five steps to successful content strategy** In her talk, Michalina will share examples and practical tips …

Check out this Meetup →

What’s happening

We have two presentations lined up, preceded by pizza and chatting!

  • Michalina will talk about five steps to successful content strategy.
  • I’ll follow with a presentation on doc fixits: What is a doc fixit (hint: a way of fixing doc bugs en masse), why would you want one, and what can you do with it once you have it?

Date, time, and location

Tuesday 3 July 2018, at 6pm. We aim to finish around 7.45pm.

At the Atlassian offices, 341 George St, Sydney.

Would you like to join us?

If you’re interested in technical documentation, you’re welcome! Sign up at the meetup and we’ll see you there.

Next Sydney Write the Docs meetup at Atlassian, July 3rd

We’ve just announced the next Write the Docs meetup in Sydney:

Sydney: Content strategy and more

Tuesday, Jul 3, 2018, 6:00 PM

341 George St, Sydney NSW 2000 Sydney, AU

3 Documentarians Attending

Join us to chat about docs – why they’re a Good Thing and how to make them even better. Tech writers, engineers, editors, product managers, more – if you’re interested in docs, you’re welcome. —————— Presenter 1: Michalina Ziemba Five steps to successful content strategy —————— More details and more presentations in the work…

Check out this Meetup →

What happens at the meetup

We currently have one speaker, Michalina, who will talk about five steps to successful content strategy.

There’ll be more speakers, and the opportunity to chat to old and new friends.

Who can attend?

If you’re interested in technical documentation, you’re welcome!

Date, time, and location

Tuesday 3 July 2018, at 6pm. We aim to finish around 7.30pm.

At the Atlassian offices, 341 George St, Sydney.

Want to air your ideas?

If you have an idea for a presentation or a lightning talk, let me know.

Thoughts on a remote Write the Docs meetup

On Wednesday this week, the Write the Docs (WtD) Australia group held a meetup entirely in cyberspace. Or, in the cloud, remote, virtual… whatever you’d like to call it. 🙂 Here are some thoughts on the experience.

Huge kudos to Swapnil Ogale for thinking up the idea of holding a remote meetup, organising it, and running it. It was a great idea and worked very well.

To attend the meetup, we all logged in to a GoToMeeting session. The meetup consisted of a few lightning talks and a couple of presentations. You can see the lineup in the meetup details.

The biggest takeaway for me is this:

People really do want to share their thoughts and experiences with others.

The lightning talks were a great way of doing that. Some presenters had slides, others just spoke from the heart. The variety of topics was intriguing, and listening to the talks was rewarding.

The chat screen was alive and humming throughout the meetup, with people commenting on the topic that the presenter was currently discussing, and on related topics, and on completely unrelated matters too. It was fun and enlightening to be able to watch the presentation and the chat at the same time. This is something that an in-person meetup doesn’t offer. During an in-person meetup, people sit quietly during the presentation, for the most part, and discussion happens afterwards.

It was good not to have to travel. I enjoyed the luxury of going straight home from work, powering up the computer, attending the meetup, then stepping out of the room to join my husband for dinner.

As with all meetups, whether virtual or in person, it was great to see everyone. Especially the speakers who enabled their video cameras so we could see their faces while they spoke.

The remote meetup was also a slightly scary experience, especially for me as a presenter.

I’ve jotted down some notes of what I found scary (I scare easily), primarily so people know they should persevere if they run into technical glitches when connecting to a remote meetup or presenting at one. Things usually work out!

We didn’t know which online platform we’d use until a until a few minutes before the meetup: candidates included Google Hangouts, YouTube streaming, or GoToMeeting. We eventually went with GoToMeeting, which worked well once it was working. I was on a Linux laptop, and the GoToMeeting compatibility checker told me I’d be unable to install the software (eek, but I’m presenting a talk!) but then it mentioned I could use the web interface. Why not just tell me all will be OK and leave it at that? Then GoToMeeting demanded a password, which I did not have. Swapnil was on that immediately, and sent a message to the group saying we should just enter a single space, which worked.

The next hiccup was audio. I couldn’t get mine working with the meetup platform on my laptop, so I dialled in on my mobile phone. All good, but five minutes later the meetup platform managed to find the audio on my laptop after all. Major audio feedback. So I had to decide whether to trust the software and kill the phone call, or mute the software and go ahead with the phone. I killed the phone call, which turned out OK, Luckily so, because by this time it was my turn to give my lightning talk.

When you’re presenting to a remote audience, it’s like talking into the void, You have no idea if people are still there. And I couldn’t get my speaker notes to play well with the meetup platform, so I had to speak without them. That went OK too!

Phew, presentation finished. It was very nice to hear people come back on the audio connection, and nice seeing the comments in the chat room about my talk.

My final thought is:

What a great community we have. Let’s do it again!

%d bloggers like this: