From 18c8c408362cd95469c2c3d2862a3eeb0e0f3c09 Mon Sep 17 00:00:00 2001 From: flicstar Date: Fri, 25 Oct 2024 14:51:31 +1100 Subject: [PATCH 1/3] Update formatting australia-2024-sessions.yaml Fixed the list items in the talks and added some extra paragraphs from pretalx. --- docs/_data/australia-2024-sessions.yaml | 145 ++++++++++++++++-------- 1 file changed, 97 insertions(+), 48 deletions(-) diff --git a/docs/_data/australia-2024-sessions.yaml b/docs/_data/australia-2024-sessions.yaml index 8734edad3..7e9793df8 100644 --- a/docs/_data/australia-2024-sessions.yaml +++ b/docs/_data/australia-2024-sessions.yaml @@ -27,7 +27,11 @@ wish it had been more bland and boring”. Instead, we wanted to open the floodgates, encourage users to provide meaningful feedback, and even feel empowered to contribute to our open source documentation - repository.

' + repository.

+ +

In this session, I’ll share the journey of implementing a documentation survey and + fixing it by dissecting the survey mechanism, enhancing feedback paths, updating our + survey design, and integrating survey results with our data analytics platform.

' - title: Creating truly accessible documentation slug: creating-truly-accessible-documentation-felicia-sephodi series: Write the Docs Australia @@ -42,11 +46,18 @@ and after I gave the talk, I had to take a technical writing for accessibility course where I learned about the art of creating useful alt text. It happened that during my slides creation, some of my examples were not inclusive of audiences - with disabilities, I later realized that was also a pattern in my workplace.

- -

This session is a mixture of what I learned in detail, creating documentation - for all users and advanced ways for making documentation usable for everyone.

' -- title: Tips for great review comments + with disabilities, I later realized that was also a pattern in my workplace. This + session is a mixture of what I learned in detail, creating documentation + for all users and advanced ways for making documentation usable for everyone.

+ +

Understanding the art of creating disability-friendly content, I will explain + the problem with the alt text during my talk and how I solved it. Additionally, + I will show ways to create effective alt text and content that adapts + depending on the user. The session will also touch on inclusive design patterns as + a method for helping create accessible documentation. Lastly, I will highlight + efforts for collaboration, testing and ensuring that everyone is on board with + accessibility in documentation design.

' +- title: Mastering review comments: Fine-tuning feedback for better docs slug: tips-for-great-review-comments-cameron-shorter series: Write the Docs Australia series_slug: australia @@ -56,20 +67,32 @@ slug: cameron-shorter twitter: website: - abstract: '

Ever received prickly feedback from a subject matter expert to your - review of their doc? Or received vague suggestions like “make this better” and - thought, “how?” Off-target or unintentionally insensitive comments can derail - collaboration, especially between technical writers, developers, and non-writers. - - When reviewing a colleague’s work, you want to improve the content while recognizing - the author’s effort. On the flip side, as the author, you often need feedback - from stakeholders who may not communicate effectively or even understand the writing - process. + abstract: '

Ever received vague review suggestions like “make this better” + and thought “how?” Or received a prickly response to your review comments from + an engineer/author and wondered “why?” Off-target or unintentionally insensitive + comments can derail collaboration, especially between technical writers, + developers, and non-writers.

+ +

When reviewing a colleague’s work, you want to improve the content while + recognizing the author’s effort. On the flip side, as the author, you often need + feedback from stakeholders who may not communicate effectively or even understand + the writing process.

+ +

In this session, you’ll learn how to give precise, respectful feedback and how to + ask for—and handle—constructive criticism. We’ll share practical tips for navigating + feedback challenges from a diverse range of stakeholders like developers, product + owners, authors, and anyone else who wants to stick their oar in.

- In this session, you’ll learn how to give precise, respectful feedback and how - to ask for—and handle—constructive criticism. We’ll share practical tips for navigating - feedback challenges from a diverse range of stakeholders like developers, product - owners, authors, and anyone else who wants to stick their oar in.

' +

This presentation is essential for anyone involved in document reviews. Drawing + on thousands of reviews from The Good Docs Project’s technical writers, we provide + actionable strategies for using tools like Google Docs, Word, LibreOffice, Pages, + GitHub, and GitLab. We’ll cover one-person reviews and managing conflicting comments + from multiple stakeholders.

+ +

Developers, writers, and docs-as-code practitioners alike will benefit from techniques + that foster smoother collaboration and improve documentation quality. You’ll leave + with practical, ready-to-use tips for feedback and communication that you can start + using straight away.

' - title: Where journalism and advertising writing skills overlap with technical writing – and where they don’t slug: where-journalism-and-advertising-writing-skills-overlap-with-technical-writing-justine-stewart @@ -90,15 +113,19 @@ by both curiosity AND altruism.

\n

I want to explain why translating developers’ explanations of software into “what’s that mean for me” for end users has a lot in common with writing a well-structured news story.

\n

Some further enticing - bullet points (because if you can’t get meta in this context, when can you?!): -

\n

• Specific writing techniques taught in journalism school that can become - part of your technical writing skillset.\n• Things journalism and advertisement - copywriting definitely DON’T have in common with technical writing – and yet, - what tips from these disciplines you might find useful. \nBONUS: How the above - can help you identify and ‘correct’ a particular feature of many AI-written documents.\n• - What the research says about the link between emotions and understanding instructions.\n• - Uncovering the best motivation to be a better technical writer.

\n

All the - answers? Definitely not. But it's always a good thing to throw around some questions!

" + bullet points (because if you can’t get meta in this context, when can you?!):

+ + + +

All the answers? Definitely not. But it's always a good thing to throw around some questions!

" - title: What if we just got AI to write the docs? slug: what-if-we-just-got-ai-to-write-the-docs-lana-brindley-she-her series: Write the Docs Australia @@ -138,17 +165,25 @@ website: abstract: "

Organisations can be very heterogeneous in their naming conventions and in their naming needs. How do we go about developing naming guidelines in - these cases?\nDifferent business units may be siloed and have strong standards - and long-established conventions, and these standards often contradict.\nA recent - project at CSIRO developing IT naming guidelines has provided me with a template - for any future such projects. \nTo succeed in getting buy-in for the adoption - of naming guidelines from management and stakeholders, both the discovery process - and the final deliverables must carefully balance factors such as:\n- Prescriptive - rules vs. loose guidance\n- Overall consistency vs. necessary differences in approach - between business units\n- Grandfathering existing practice vs. starting fresh\n- - Meaningfulness and searchability vs. uniqueness (e.g. including IDs in names)\n- - Detailed guidance vs. quick reference value\n- Addressing current project scope - vs. later scalability to organisation-wide guidelines

" + these cases? Different business units may be siloed and have strong standards + and long-established conventions, and these standards often contradict.

+

A recent project at CSIRO developing IT naming guidelines has provided me + with a template for any future such projects.

+

To succeed in getting buy-in for the adoption of naming guidelines from + management and stakeholders, both the discovery process and the final deliverables + must carefully balance factors such as:

+ +

The insights from this project are interesting because (at project kick-off) the organisation + was an outlier in how disparate the approaches of different business units towards naming and + categorising assets were (even within IT), and also how different their needs were.

" - title: Snack Videos for your Audience slug: snack-videos-for-your-audience-ruth series: Write the Docs Australia @@ -160,18 +195,24 @@ twitter: website: abstract: "

We wanted to make our knowledge centres' content more digestible. - While our current articles are available to be read, but what about people who + While our current articles are available to be read, what about people who have difficulty reading or learning. We recognized the need for alternative methods of learning for those who struggle with reading, comprehension, or prefer visual - learning.\nIt was time to make a change, so we invested in making short videos + learning.

+

It was time to make a change, so we invested in making short videos instead of the previous hour-long videos or re-purposed webinars. Now, people - can snack video instead of eating a meal.\nIn this talk, I will cover the following:\n• - \ Reasons behind our approach with looking at how different generations learn - and the importance of learning accessibility. \n• Explore the video foundations, - such as scripts, as it is still important to have written words. \n• Look at - the learner’s mental models and how bite-sized learning can be easily digested. - \n• Give an overview of the production process that you can implement.\nAnd - finally, it is showtime and we will watch 2 short videos.

" + can snack video instead of eating a meal.

+ +

In this talk, I will cover the following:

+ + +

And finally, it is showtime and we will watch 2 short videos.

" - title: 'Global Voices, Inclusive Docs: How Open-Source Sets the Standard for Inclusivity and How You Can Too' slug: global-voices-inclusive-docs-how-open-source-sets-the-standard-for-inclusivity-eeshaan-sawant @@ -192,6 +233,14 @@ and multilingual accessibility. By the end of this talk, attendees will gain practical insights to implement these inclusive standards in their work, ensuring their documentation is welcoming and accessible to all.

+ +

This talk highlights a critical issue in the tech industry: THE LACK OF INCLUSIVITY. + While this problem spans multiple sectors, we will focus specifically on documentation. + We'll explore how language barriers, gender biases, and accessibility gaps have + historically excluded many from fully engaging with technical content. We'll also + look at how some of the most successful open-source communities, such as Kubernetes + and the Linux Foundation, have faced inclusivity challenges before, how they have + tackled them head-on, and what we can learn from their experiences.

- title: Brick Docs Workshop slug: brick-docs-workshop-yvonne-perkins series: Write the Docs Australia From 6649ed1a5fc52ac5780c8a5d86053b2aa00cce17 Mon Sep 17 00:00:00 2001 From: flicstar Date: Fri, 25 Oct 2024 15:10:06 +1100 Subject: [PATCH 2/3] Update australia-2024-sessions.yaml --- docs/_data/australia-2024-sessions.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_data/australia-2024-sessions.yaml b/docs/_data/australia-2024-sessions.yaml index 7e9793df8..711989c3d 100644 --- a/docs/_data/australia-2024-sessions.yaml +++ b/docs/_data/australia-2024-sessions.yaml @@ -57,7 +57,7 @@ a method for helping create accessible documentation. Lastly, I will highlight efforts for collaboration, testing and ensuring that everyone is on board with accessibility in documentation design.

' -- title: Mastering review comments: Fine-tuning feedback for better docs +- title: Mastering review comments — Fine-tuning feedback for better docs slug: tips-for-great-review-comments-cameron-shorter series: Write the Docs Australia series_slug: australia From 249171f56349423d910c3bb537c6b83b1bd4e34b Mon Sep 17 00:00:00 2001 From: Swapnil Ogale Date: Fri, 25 Oct 2024 16:08:26 +1100 Subject: [PATCH 3/3] Fixed error --- docs/_data/australia-2024-sessions.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_data/australia-2024-sessions.yaml b/docs/_data/australia-2024-sessions.yaml index 711989c3d..66a2cd673 100644 --- a/docs/_data/australia-2024-sessions.yaml +++ b/docs/_data/australia-2024-sessions.yaml @@ -234,7 +234,7 @@ insights to implement these inclusive standards in their work, ensuring their documentation is welcoming and accessible to all.

-

This talk highlights a critical issue in the tech industry: THE LACK OF INCLUSIVITY. +

This talk highlights a critical issue in the tech industry - THE LACK OF INCLUSIVITY. While this problem spans multiple sectors, we will focus specifically on documentation. We'll explore how language barriers, gender biases, and accessibility gaps have historically excluded many from fully engaging with technical content. We'll also