WTD Episode 17: Structured writing — reasons and approaches

Write the Docs Podcast

#Podcasting Education #Write The Docs

1:15:36

In this episode, we welcome back David French, columnist for The New York Times , former constitutional attorney, and author of Divided We Fall . We discuss the current state of American democracy, the challenges of political division, and how we can engage in civil discourse despite deep ideological differences. David also shares a personal update on his family and reflects on the profound trials and growth that come with adversity. 📌 What We Discuss: ✔️ How David and his family navigated the challenges of a serious health crisis. ✔️ The rise of political polarization and the factors driving it. ✔️ Why distinguishing between “unwise, unethical, and unlawful” is crucial in analyzing political actions. ✔️ How consuming different perspectives (even opposing ones) helps in understanding political dynamics. ✔️ The role of Christian values in politics and how they are being redefined. ⏳ Episode Highlights 📍 [00:01:00] – David French’s background and his journey from litigation to journalism. 📍 [00:02:30] – Personal update: David shares his wife Nancy’s battle with cancer and their journey as a family. 📍 [00:06:00] – How to navigate personal trials while maintaining faith and resilience. 📍 [00:10:00] – The danger of political paranoia and the pitfalls of extreme polarization. 📍 [00:18:00] – The "friend-enemy" paradigm in American politics and its influence in Christian fundamentalism. 📍 [00:24:00] – Revisiting Divided We Fall : How America’s divisions have devolved since 2020. 📍 [00:40:00] – The categories and differences of unwise, unethical, and unlawful political actions. 📍 [00:55:00] – The balance between justice, kindness, and humility in political engagement. 📍 [01:00:00] – The After Party initiative: A Christian approach to politics focused on values rather than policy. 💬 Featured Quotes 🔹 "You don't know who you truly are until your values are tested." – David French 🔹 "If we focus on the relational, we can have better conversations even across deep differences." – Corey Nathan 🔹 "Justice, kindness, and humility—if you're missing one, you're doing it wrong." – David French 🔹 "The United States has a history of shifting without repenting. We just move on." – David French 📚 Resources Mentioned David French’s Writing: New York Times David’s Book: Divided We Fall The After Party Initiative – More Info Advisory Opinions Podcast (with Sarah Isgur & David French) – Listen Here 📣 Call to Action If you found this conversation insightful, please: ✅ Subscribe to Talkin' Politics & Religion Without Killin' Each Other on your favorite podcast platform. ✅ Leave a review on Apple Podcasts, Spotify, or wherever you listen: ratethispodcast.com/goodfaithpolitics ✅ Support the show on Patreon: patreon.com/politicsandreligion ✅ Watch the full conversation and subscribe on YouTube: youtube.com/@politicsandreligion 🔗 Connect With Us on Social Media @coreysnathan: Bluesky LinkedIn Instagram Threads Facebook Substack David French: 🔗 Twitter | BlueSky | New York Times Our Sponsors Meza Wealth Management: www.mezawealth.com Prolux Autogroup: www.proluxautogroup.com or www.granadahillsairporttransportation.com Let’s keep talking politics and religion—with gentleness and respect. 🎙️💡…

6年之前 58:38

MP3•单集首页

In this Write the Docs podcast episode, we chat with Mark Baker about structured writing, specifically focusing on his new book Structured Writing: Rhetoric and Process. After introducing and defining structured writing, Mark explains the four domains you can add structure: media, document, subject, and management domains. He explains the advantages of working with structure in the subject domain, and why mixing structure across subject and document domains can be inefficient. We also chat about how structured writing connects with SEO and microformats on the semantic web, the limits of structure in Markdown formats, how to implement structure in linking, and more.

35集单集

Write the Docs Podcast

WTD Episode 17: Structured writing — reasons and approaches

Write the Docs Podcast

published 6年之前

MP3•单集首页

35集单集

#Podcasting Education #Write The Docs

所有剧集

Write the Docs Podcast

1
WTD Episode 35: Docs for Developers book, with Jared Bhatti and Zachary Sarah Corleissen 57:00

3 years之前57:00

57:00

In this podcast, we discuss the newly released book Docs for Developers: An Engineer's Field Guide to Technical Writing with Jared Bhatti, staff technical writer at Google, and Zachary Sarah Corleissen, staff technical writer at Stripe (two of the co-authors). This book on writing documentation focuses on the end-to-end writing process (from audience analysis to drafting, editing, publishing, and more) and is written specifically with developers in mind. The authors use the scenario of documenting Corg.ly, an API that translates barks, as a common thread through each of the chapters.…

Write the Docs Podcast

1
WTD Episode 34: Adding personality to documentation, with Fabrizio Ferri 43:05

4 years之前43:05

43:05

In this podcast, Fabrizio Ferri joins us for a discussion about adding both personal identity and personality to documentation. Why are the docs we write so often anonymous, and does that anonymity work against progress in our careers? Are tech writers, who are typically introverts, averse to publicity, or does our industry not allow for it? And if you want to be a "personality" in the tech communications world, what do you do? How do you add personality constructively to your work without disrupting corporate brand and consistency?…

Write the Docs Podcast

1
WTD Episode 33: Simplified user interfaces, with Anton Bollen 58:38

4 years之前58:38

58:38

One of the most challenging and frustrating things about being a tech writer is managing screenshots in your product documentation. How many times have you needed to take complex screenshots of your product and meticulously marked them up with callouts only to be told that a field has changed and you need to do everything again? It’s so frustrating and demoralizing as a writer because it feels like wasted effort. What if there was a way to create screenshots that could withstand the rapid iterations of a product under development while still conveying valuable meaning to your readers. Today we’re joined by Anton Bollen from TechSmith who explains how we can do this using low-detail screenshots, aka simplified user interfaces, that let you focus your users' attention on just the bits of the interface that matter.…

Write the Docs Podcast

1
WTD Episode 32: Self-publishing and AsciiDoc, with Mehmed Pasic 54:09

4 years之前54:09

54:09

Many tech writers are familiar with using AsciiDoc for documentation, but did you know that you can also create fiction and non-fiction books with AsciiDoc, publishing to popular digital formats such as EPUB or PDF, along with HTML? In this episode of the Write the Docs podcast, we chat with Mehmed Pasic from Manning Publications about self-publishing, AsciiDoc, collaborative workflows between authors and editors, trends in book publishing, the most popular devices for consuming content, book versus video formats for technical content, and more.…

Write the Docs Podcast

1
WTD Episode 31: Strategies for site search, with Peter Levan 1:00:57

5 years之前1:00:57

1:00:57

So many documentation websites rely on search as part of their information architecture. But what do you actually need to consider if you want to make your site search return answers for users in relevant, efficient ways? Join Peter Levan from Funnelback with regular guests Chris, Jared, and Tom for a talk all about making search work well on your site. Some of the questions discussed include: Why can't you just let Google do the searching and indexing for you? Do you need to pay big money to get a site search tool? How do you make your docs site talk robot ?…

Write the Docs Podcast

1
WTD Episode 30: Documentation templates, with Juan Lara 1:01:56

5 years之前1:01:56

1:01:56

In this episode, Juan Lara from Google joins us for a lively discussion about documentation templates. Documentation templates refer to established patterns we follow for common documentation types, such as quickstarts, how-to guides, concepts, tutorials, reference, troubleshooting, release notes, FAQs, or other information types that have similar, predictable patterns. Templates can be helpful in orienting new writers, but they can also help ensure consistency among larger groups of experienced writers too. Our discussion in this episode ranges from observations about when templates are right for users versus writers, and how templates fit into an overall content strategy and information architecture. Beyond templates, your user's goals and journeys will influence the shape of your help content.…

Write the Docs Podcast

1
WTD Episode 29: Salary Survey results and WFH tips, with Eric Holscher 56:03

5 years之前56:03

56:03

In this episode, we chat with Eric Holscher, co-founder of both Read the Docs and Write the Docs, about the recent Salary Survey that the WTD group conducted. This survey was launched in Fall 2019, and the results published were recently published. The salary survey covers details such as types of employment, job titles, roles, length of time in role, work location, annual salary, salary breakdowns by state, additional benefits, satisfaction, reasons for dissastisfaction, organization type, respondent demographics, and more. In addition to exploring the survey, we also chat about tips for working from home, especially given that both Eric and Chris have been working remotely for many years.…

Write the Docs Podcast

1
WTD Episode 28: UX writing - Starting and Scaling at your Company, Berlin WTD meetup 1:14:54

5 years之前1:14:54

1:14:54

Episode 28 is a recording of a Berlin WTD meetup focused on UX writing processes, live streamed on March 9, 2020 at the Humanitec in Berlin. The meetup featured two speakers. Natasha Sarana, UX Writer at FlixMobility, talks about her company's attempts to include UX Writing in their research routine. She shares the main challenges they faced so far and how they deal with them. The second speaker, Roger Sheen, information architect and freelance UX Writer, talks about how the UI copy process at Wire evolved as the product matured. He covers gathering and aligning copy from source code, moving it to dedicated strings files to facilitate version control and localization, and setting up collaboration workflows with developers and external partners.…

Write the Docs Podcast

1
WTD Episode 27: Starting a doc group/process when you're the first 57:43

5 years之前57:43

57:43

In episode 27 of the Write the Docs podcast, we're joined by Cynthia Ng and Amy Qualls from GitLab to talk about strategies for starting up docs in organizations where there aren't any other tech writers and where you're first on scene setting up shop. What are your first steps as a documentarian when there isn't anyone else, when processes, contacts, tools, and other systems aren't documented or described anywhere? When you're first on scene, docs might not even be your full-time job but rather a task that's on the side of your desk and which you have to bootstrap from ground zero.…

Write the Docs Podcast

1
WTD Episode 26: Tech Writing and Reddit, with Alan Bowman 1:04:24

5 years之前1:04:24

1:04:24

In episode 26, we talk with Alan Bowman about the technical writing forum on Reddit as well as the WTD Slack channel, comparing and contrasting the two spaces. Topics covered include pros and cons of anonymity on the internet, transparency around sensitive or taboo topics (e.g., salary, masters programs, feelings of overwhelm), age/experience demographics for both communities, balancing honesty with professionalism, responding to posts from overwhelmed tech writers, dealing with recurring topics, strategies for participating, and more.…

Write the Docs Podcast

1
WTD Episode 25: Researching how developers use API docs, with Andrew Head 56:14

5 years之前56:14

56:14

In episode 25, we talk with Andrew Head, Ph.D. Candidate in Computer Science at UC Berkeley, about his research on how developers use API documentation. Specifically, we focused on a recent article he co-authored titled When Not to Comment: Questions and Tradeoffs with API Documentation for C++ Projects . During the podcast, we chat about the following: where developers look for information, how developers manage information in Google’s unique billion-line code base, when it's appropriate to just let developers read the code directly versus creating documentation, what kind of information developers look for in API documentation, the relevance of document generators such as Doxygen, and more. Andrew also talked about some projects he's working on to build interactive tools for developers to share code expertise.…

Write the Docs Podcast

1
WTD Episode 24: Conference chatter and the Australian scene, with Swapnil Ogale 55:20

6 years之前55:20

55:20

In this episode, we're joined by the Write the Docs Australia initiator Swapnil Ogale. We talk about conference wind-downs and ramp-ups, highlights from the just-finished WTD Prague conference, speakers announced for upcoming Write the Docs Australia conference, the Good Docs Project, the tech writing scene in Australia, and more.…

Write the Docs Podcast

1
WTD Episode 23: How to write inclusive tech documentation, by Lucie Le Naour 38:42

6 years之前38:42

38:42

In this episode, rather than the usual roundtable discussion, we provide a recording of a WTD Berlin presentation by Lucie Le Naour on how to write inclusive tech documentation. Inclusive documentation takes into account all users, regardless of their gender, culture, or abilities. It uses language that treats different types of people fairly and equally, acknowledging that the words you choose matter in the connotations and attitudes they convey. This presentation was recorded on August 19, 2019 in Berlin.…

Write the Docs Podcast

1
WTD Episode 22: Managing multiple doc projects across Git repositories, with Giles Gaskell 1:01:40

6 years之前1:01:40

1:01:40

In episode 22, Giles Gaskell from Squiz in Australia joins us to talk about managing multiple doc projects across Git repositories through Antora. Giles explains how to establish processes such that updating documentation becomes part of the definition of done, how to manage build process across multiple Gitlab repositories, strategies for distributing doc work across engineers through templates, how to scale workloads when you're the lone technical writer in the company, times when dogfooding your own product for docs makes sense and when it does not, pros and cons of Asciidoc versus Markdown, and more docs-as-code topics.…

Write the Docs Podcast

1
WTD Episode 21: On career growth, leadership, and mentoring in tech writing, with Becky Todd 59:21

6 years之前59:21