Season of docs retro
•
0 likes•9 views
Season of Docs is an initiative where developers spend a month improving documentation for open source projects. The author learned that documentation is important for helping others use projects and that contributing documentation is a way to help open source communities. Season of Docs encourages participation to strengthen project documentation for the benefit of all users.
Recommended
More Related Content
Recently uploaded
Recently uploaded (20)
Featured
Featured (20)
Season of docs retro
- 3. Season of Docs Why you should do it
- 8. What is Season of Docs?
- 12. What did I learn?
- 19. Why should I do it?
- 24. Takeaways
- 26. Show up. Do the work.
- 29. flicstar.com
Editor's Notes
- I’ve been working as a tech writer for over 10 years. Up until last year, I’d always worked in traditional offices in the corporate world --documenting software. Last year, I went freelance and now I contract to an agency who provides writing services to open source projects and communities. I’m also part of an embryonic open source initiative called The Good Docs project...
- And I participated in the inaugural Google Season of Docs program and that is what I’m going to talk to you about tonight. How many of you have some experience working in open source communities? Okay, well feel free to zone out for 20 minutes, see you on the flip side.
- For the rest of you, in case you didn’t know, the future is now. I’m not going to explain what open source is, so too bad so sad if you don’t know. What I AM going to talk about is my experience coming from a corporate world what is was like writing for an open source project.
- Maybe you’ve been thinking about “getting into” open source BUT it can be daunting and there are barriers to entry.
- Most of us just want to feel safe and secure.
- Let me show you why Season of Docs is the answer.
- It was a program run by Google that ran from March to December - and there are still some long running projects which are due to finish up this month. Here’s a direct quote from their website….The goal of SoD was to “provide a framework for tech writers and open source projects to work together towards the common goal of improving an open source project's documentation.”
- So here’s how it worked: Open source organizations were invited to submit projects. Google chose about 50 of these and published them. Tech Writers were then invited to submit proposals. Google matched writers to projects. Every writer got a mentor from within the community. Then work began. The actual writing period was about 3 months long. During the program, there was clear guidance about timelines and expectation management for both writers and organizations. The website held comprehensive documentation (of excellent quality) from Sarah Maddox and Andrew Chen. There was also a Slack team and email group. Writers and organisations had to submit a project report at the end of the program.
- A little bit about the work I did. The Open Source Geospatial Foundation (OSGeo) has a large number of separate software projects. One of their initiatives is called OSGeoLive, which is a USB of about 50 pieces of software that you can try out which they hand out at conferences. Each of these projects had a Quickstart tutorial. The work I undertook was to review the Quickstart tutorials based on a template. The actual nuts and bolts of what I did was: installed OSGeoLive on a virtual machine reviewed the existing docs against the software The documents were housed in a github repository so I used git to create to a pull request per doc and comment on my proposed changes. Worked with doc owners to obtain their approval to merge my suggested changes.
- My overall experience with the program was positive. It was excellently run by Google. I found the OSGeo community to be welcoming, friendly and professional. It helped that there was with some synchronous worktime (timezone overlap) so I could attend IRC (internet relay chat) meetings. I also lucked on to an excellent mentor, an open source veteran, who helped me through culture shock coming from the corporate world. But that’s just my story. You can go and read every writer’s project report because they’re publicly available on the Season of Docs Results page https://developers.google.com/season-of-docs/docs/participants I would recommend you do that to see the breadth and the variety of work that was done and to read about others’ experience.
- Let’s look at the differences between working in the corporate world and open source. The writing itself is the same. Tech writing is tech writing. It’s the surrounding pieces that are different and you need to manage that because often, you can’t just dive in and start writing. In order to understand your PAD (purpose, audience, delivery) you need to adopt the culture of the community and learn their tools and processes.
- Eric S Raymond, an open source advocate, wrote a book called “The Cathedral and the Bazaar”. In it, he describes open source development as “a great babbling bazaar of differing agendas and approaches ... out of which a coherent and stable system seemingly emerges only by a succession of miracles.” With open source, you're coming into an established community who have been working hard to get to where they are. Which is not unlike a business. But it can be daunting to gain a foothold in the community.
- Most open source communities are distributed communities. Fabian Pfortmüller explains that that means they’ve probably developed over a period of time, they have a strong sense of shared identity and they want to co-create or feel co-ownership of work. So you’re at the bazaar and you want make connections so that you can start doing some work. You want to build rapport but the only thing you know about people is their username. So the first thing you want to do is try to heighten your awareness of the group- consider that “shared identify”. And look for the Code of Conduct - which will typically be about respect, inclusion and honesty.
- I found that, coming from the corporate world, the email culture in open source was something I had to get used to. The OSGeo project communicated mainly via public mailing lists. Mailing lists are often used by open source communities because they offer conversation threading and they’re easily archived. Sending to the group mailing list felt like sending a company-wide email -- it took some getting used to. In a work environment, when you send an email, you just include your stakeholders. In open source...remember, you're at the babbling bazaar! Remember that this distributed communities maybe wants to co-create or at least wants to feel co-ownership. A developer friend of mine explained it to me. If you don't send to the mailing list you might actually be cutting people out of the loop who are interested bystanders or who might have something useful to add. The mailing lists are opt-in. If people find them too noisy or irrelevant, they'll opt-out. And he said, if you see a noisy email list then people will accept you adding your own noise to the thing. I had to send a lot of emails as part of the project I did for OSGeo. I had to connect with document owners personally, and speak to the wider community as well. I had to manage expectations about what I was doing and gauge interest--or otherwise-- for people to be involved in my work. It takes time to send lots of emails. Use empathy to craft your message. Here’s a quote from my mentor: “Engaging the community takes time and effort. It can be as time-consuming as doing technical writing work. Allow for this time when planning your project.”
- So we’ve got the comms sorted, what’s next? The actual work. Here’s another quote. This is from Guy Martin who works at Autodesk. He says that “You have to earn your role in the community. The only way to do that is to gain credibility and make contributions.” In the corporate world, when you’re hired to do a job, your new colleagues trust that you know how to do that job because you’ve been hired to do so. In open source, you have to build your reputation. Commit to doing the work, and then do the work that you commit to. And that’s going to build trust pretty quickly.
- But there is a learning curve. You are going to have to overcome some hurdles. In terms of process, look for the Contributors Guide. You may need to set up accounts, request access and permissions to be able to do what you need to do. While you’re busy getting set up, you can build credibility by starting to talk to people, turn up to meetings and just generally show an interest.
- As tech writers i think we’re used to getting up to speed with new tools quickly. Jumping into an open source project is no different. But in this case you’re more than likely going to be working with other open source tools to do your: Writing version control and publishing. You’re halfway there if you’re already familiar with git, some flavour of markdown, Linux and maybe even working with the command line. Okay, so you’re feeling confident--but don’t try to show off your skills just yet! This is from an article I read in Hackernoon about open source, and it says: “...don’t try to show off your skills, in fact, look for the easiest thing you can find.” This is often labelled as a “good first issue”. Communities will identify easier tasks for new contributors which can help you run through the end-to-end process to iron out any wrinkles with tools and permissions.
- So that all sounds pretty hard. The Season of Docs program gives you: communities who have opted in a defined piece of work with a deadline and a buddy
- Communities opt-in to the program. They have had to articulate their problem and propose a discrete chunk of work that requires a tech writer. This means you don’t have to find a “good first issue”. And you’ve got communities who are predisposed to help you succeed.
- The constraints of the program mean you’re not working with something nebulous. You’ve got a nice contained piece of work with boundaries and a deadline, which reduces the risk of scope creep. And when you reach the end-date, if it’s not for you, you can gracefully step away.
- The beauty of the SoD program is that you have a “buddy” in the form of your mentor. They help you with the people and they help you with the tools. They also help you track to time and they’ve got your back if you make a mistake. It’s a very secure way to work.
- What else do you get? Personal growth! Reputation building, you’re learning new tools, gaining writing experience. It all adds to your employability, connections, and future job opportunities. Helping out - Like any volunteer work, you usually get more out of it compared to what you put in. Personally, I learnt new markup language, stretched my git muscles and made new friends.
- When in Rome, do as the Romans do. Abide by the code of conduct and follow the conventions of the community. Remember to heighten your awareness of the group Even if you do know a better tool to use or a better way to do things, don't lead with that. Establish your chops first.
- Be available to commit your time. Do the work you commit to. It’s your reputation on the line.
- Season of Docs 2020 has not yet been announced but they have appointed a program director so it’s fairly to be on again. She asked me to say that you can follow the Google Open Source blog for updates.
- If you can’t wait, there are a couple of channels in the WtD Slack team if you’re looking for opportunities to get involved.
- That’s a wrap. I’ve posted a page for this talk on my site which includes all my references and credits the images I used in my slides tonight. I’d love to open the floor up for discussion and hear any questions or find out about other people’s experiences. Thank you.