Documentation and Open Source with Anne Gentle
08/26/21 • 28 min
There is a perception in the tech world that developer documentation is boring, and it can be a major challenge to get people to contribute to open source docs. Luckily, today’s guest, lifelong learner Anne Gentle, is always up for a challenge. Anne’s open source journey began by volunteering for organizations such as One Laptop per Child, and getting involved with book sprints. This was a way for her to learn about innovative techniques being used in open source which she was missing in her job as an everyday technical writer. The value she gained from entering the world of open source documentation, and the value she could see it provided to organizations, inspired Anne to write a book; Docs Like Code. In today’s episode, Anne shares some of the principles she covers in her book, explains the parallels that exist between documentation and software development, dives into some industry changes which have transformed documentation over the past few years, and offers valuable advice for anyone interested in getting involved in open source.
Key Points From This Episode:
- Anne explains where open source and documentation intersect.
- Why Anne chose to get involved with open source volunteering.
- A variety of other reasons that lead people into the world of open source volunteering.
- Growth in the number of open source writers over the years.
- Using GitHub as an example, Anne explains the value of open source to organizations.
- Why DOCSIS code techniques pair well with open source.
- The motivation behind Anne’s book, Docs Like Code.
- Industry changes which influenced the documentation changes.
- Parallels between software development and documentation.
- Advice from Anne regarding putting systems in place for writers.
- How the CICD has been helpful for documentation.
- The factor that is vital to successful documentation.
- What Anne wished she knew more of before entering the open source world.
- Anne’s biggest surprise when she started working in open source.
- How the open source ethos is applicable to Anne’s current role.
- Valuable advice from Anne for anyone interested in open source.
- Google's Season of Docs program, and the impacts that Anne expects it to have.
Links Mentioned in Today’s Episode:
There is a perception in the tech world that developer documentation is boring, and it can be a major challenge to get people to contribute to open source docs. Luckily, today’s guest, lifelong learner Anne Gentle, is always up for a challenge. Anne’s open source journey began by volunteering for organizations such as One Laptop per Child, and getting involved with book sprints. This was a way for her to learn about innovative techniques being used in open source which she was missing in her job as an everyday technical writer. The value she gained from entering the world of open source documentation, and the value she could see it provided to organizations, inspired Anne to write a book; Docs Like Code. In today’s episode, Anne shares some of the principles she covers in her book, explains the parallels that exist between documentation and software development, dives into some industry changes which have transformed documentation over the past few years, and offers valuable advice for anyone interested in getting involved in open source.
Key Points From This Episode:
- Anne explains where open source and documentation intersect.
- Why Anne chose to get involved with open source volunteering.
- A variety of other reasons that lead people into the world of open source volunteering.
- Growth in the number of open source writers over the years.
- Using GitHub as an example, Anne explains the value of open source to organizations.
- Why DOCSIS code techniques pair well with open source.
- The motivation behind Anne’s book, Docs Like Code.
- Industry changes which influenced the documentation changes.
- Parallels between software development and documentation.
- Advice from Anne regarding putting systems in place for writers.
- How the CICD has been helpful for documentation.
- The factor that is vital to successful documentation.
- What Anne wished she knew more of before entering the open source world.
- Anne’s biggest surprise when she started working in open source.
- How the open source ethos is applicable to Anne’s current role.
- Valuable advice from Anne for anyone interested in open source.
- Google's Season of Docs program, and the impacts that Anne expects it to have.
Links Mentioned in Today’s Episode:
Previous Episode
Diversity and Inclusion in Open Source with Amy Marrich
The focus of today's discussion is the important conversation and project of diversity and inclusion in the open-source space. Joining us to share her expertise and experience on the topic is Amy Marrich from the CHAOSS Project and someone who has dedicated much time and energy to creating more accessible and comfortable spaces for a wider range of people. In our chat, we get to hear how Amy became curious and got involved in this side of open-source work before she unpacks some of the layers of why these goals are so important. Listeners will get a basic understanding from our guest, as she provides some very helpful definitions and reflections, that are great departure points, no matter your knowledge level. Our guest also weighs in on how she measures the success of the work she does in inclusion and diversity, and to round things out, shares an inspiring anecdote that illustrates the importance of this work!
Key Points From This Episode:
- A basic definition of diversity and inclusion and how these concepts have evolved.
- Why the ideas and practices of diversity and inclusion are important in the open source world.
- How larger social issues tie into the tech and software professions.
- The coming to light of the relevant issues, and Amy's experiences and discoveries.
- Best practices and current initiatives that are helping the diversity and inclusion cause.
- Determining priorities and the most critical issues to address at any time.
- The surveys that Amy and her team use to measure the success of initiatives.
- Amy's thoughts on the current state of things and how far we still have to go.
- Addressing individual concerns of exclusion and the importance of speaking up
- A success story from Amy's work that shows the impact of people feeling welcome and safe.
- Why Amy prioritizes comfort and belonging and uses this as the main measure of success.
Links Mentioned in Today’s Episode:
TODO Group https://todogroup.org/
Next Episode
Open Source for Good with Kevin Fleming
Bloomberg has been fostering open solutions for the financial industry for quite some time, so it should come as no surprise that they also have been actively engaged in the open source community, with an eye toward promoting more rapid innovation across all aspects of the organization worldwide. Today, we're talking about open source for good with a Member of the Bloomberg CTO Office, Kevin Fleming. Kevin focuses on Bloomberg’s technology community engagement, including the company's involvement in open source projects and standards. He has been an open-source developer and project manager for nearly three decades and, in today’s episode, he shares what the term ‘open source for good’ means to Bloomberg and how it fits into the company’s strong philanthropic history. Tuning in, you’ll learn about the reciprocal relationship Bloomberg has built with the open-source community, some of the hurdles Kevin has had to overcome in implementing the open-source programs at Bloomberg, and the main benefits of these programs for Bloomberg and other organizations, plus a whole lot more! We hope you’ll join us.
Key Points From This Episode:
- How Bloomberg benefits from open source technology, including better tools, community participation, and skill building for their engineers.
- The reciprocal relationship that Bloomberg has built with the open source community.
- How the concept of ‘open source for good’ fits into Bloomberg’s strong philanthropic history.
- How the program changed over time and what they learned from its successes and failures.
- Learn about Tech at Bloomberg, the company’s innovation communications brand.
- Kevin describes the time and resources that go into user experience design at Bloomberg.
- How open source software has evolved to become increasingly end user facing.
- Some of the hurdles that Kevin has had to overcome, such as figuring out how to educate ‘non-technologists’ about open source.
- The main benefit of Bloomberg’s open source programs: continuous education for software developers in a rapidly evolving landscape.
- Why Kevin is hopeful that we’ll see more Fortune 500 companies taking on similar programs.
- The spirit of collaboration rather than competition that could grow this idea.
Links Mentioned in Today’s Episode:
If you like this episode you’ll love
Episode Comments
Generate a badge
Get a badge for your website that links back to this episode
<a href="https://goodpods.com/podcasts/the-octopod-conversations-with-suses-office-of-the-cto-231075/documentation-and-open-source-with-anne-gentle-26036347"> <img src="https://storage.googleapis.com/goodpods-images-bucket/badges/generic-badge-1.svg" alt="listen to documentation and open source with anne gentle on goodpods" style="width: 225px" /> </a>
Copy