Suggest modification to this talk

Title

Description

Carmen Chung

Ever heard of “cscareerthrowaway567”, the software engineer who lost his job on the first day of work? This happened because of terrible internal documentation - something that is surprisingly common in the tech industry.Follow along with Carmen on the journey of three employees of Big Tech Co (a company that uses Ruby on Rails): junior software developer, Kira; senior software engineer Felicity; and product manager Franco, as they struggle to navigate the day’s hurdles because of poor technical documentation at their company.

Carmen is a software engineer, writer, and conference speaker, with a reputation for breaking people's code. Prior to her move into tech, she worked internationally as a corporate lawyer for almost seven years.

During the day, she is a software engineer at Valiant Finance, and at night, she's the host and producer of a YouTube channel called CodeFights, which teaches people how to solve coding questions in 15 minutes. In her spare time, she teaches flexibility classes, creates (often absurd) side projects, and fosters rescue dogs.

Produced by NDV: https://youtube.com/channel/UCQ7dFBzZGlBvtU2hCecsBBg?sub_confirmation=1

#ruby #rubyconf #rubyconfau #rubyconf_au #rails #programming

Fri Feb 21 13:30:00 2020 at Plenary Room

Date

Summarized using AI?

If this talk's summary was generated by AI, please check this box. A "Summarized using AI" badge will be displayed in the summary tab to indicate that the summary was generated using AI.

Show "Summarized using AI" badge on summary page

Summary

Markdown supported

In this RubyConf AU 2020 presentation, Carmen Chung delivers valuable insights on writing effective technical documentation that can significantly impact a software developer's career. She illustrates the importance of robust documentation through the story of Kira, a junior developer at Big Tech Co, whose first day was marred by confusing and outdated internal documentation.

The video begins by emphasizing the real-life consequences of poor documentation, referencing a Reddit post by ‘CS career throwaway 567’ who destroyed a production database on their first day due to inadequate guidance. Through Kira's experience, Carmen outlines key strategies for creating beneficial tech documentation:

- **Choose Appropriate Titles**: Titles should be descriptive and easily searchable. Kira struggled to find information because the document was called 'Document That Explains Everything,' which is neither helpful nor specific.
- **Provide Clear Structure**: Documentation should include an index or table of contents, and break down lengthy content into manageable sections with navigable headings. The absence of such structure made Kira’s 600-page document overwhelming and non-functional.
- **Regular Updates**: Keeping documentation current is essential. Kira's document was outdated (from 2007) and led to compatibility issues. Incorporating documentation updates into regular workflows can prevent similar situations in the future.
- **Utilize Clear Code Examples**: Properly formatted code samples can aid comprehension. Kira's confusion stemmed partly from poorly formatted commands which did not clearly separate instructional text from executable code.
- **Detailed Commit Messages and Documentation**: Clear communication regarding changes, such as commit messages and pull requests, ensures that all team members understand updates to any project. Carmen illustrates this through Felicity's frustrated response to Kira's mistake, which could have been mitigated with better documentation practices.

Carmen concludes the presentation by reiterating that effective documentation leads to better communication, less confusion, and ultimately saves careers. She strongly advocates for an organized and collaborative approach to writing, maintaining, and updating technical documentation.

Carmen invites developers to prioritize clarity and structure in their documentation efforts, ensuring that both they and new hires are equipped to succeed.

Cancel