Katie edits

.github/workflows/vale.yml

@@ -19,6 +19,9 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Install docutilsfor rst2html
+        run: sudo apt-get install -y docutils
+
       - name: Linter
         uses: errata-ai/vale-action@reviewdog
         env:

README.md

@@ -2,11 +2,11 @@
 
 This is the code that powers [www.writethedocs.org](http://www.writethedocs.org). It contains information about the Write the Docs group, as well as information about writing documentation.
 
-To contribute to the Write the Docs website, it's helpful to familiarize yourself with the [Sphinx site generator](https://www.sphinx-doc.org/), as well as [reStructuredText markup syntax](https://www.sphinx-doc.org/en/stable/rest.html).
+To contribute to the Write the Docs website, it's helpful to familiarize yourself with the [Sphinx site generator](https://www.sphinx-doc.org/) and [reStructuredText markup syntax](https://www.sphinx-doc.org/en/stable/rest.html).
 
 ### Code Architecture
 
-All of the generated website lives inside the `docs` directory, but many files outside the `conf/` directory are just static RST, as in any other Sphinx project.
+All of the generated website lives inside the `docs` directory, but many files outside the `conf/` directory are just static RST like any other Sphinx project.
 
 All RST files are rendered with [Jinja](https://jinja.palletsprojects.com/), which allows the use of Jinja tags in all of them. A few custom Jinja filters are available for things like generating photo paths for speakers.
 
@@ -58,7 +58,7 @@ If you run into trouble with broken links to video files, have a look at `_ext/f
 
 ### Installing the project requirements
 
-1. Activate the virtual environment according to your operating system:
+1. Activate the virtual environment as per your operating system:
 
     * On Linux-based systems, run `source venv/bin/activate`.
     * On Windows using the Command Prompt, run `venv\Scripts\activate.bat`.

docs/_data/australia-2024-schedule.yaml

@@ -86,7 +86,7 @@ talks_day2:
   - duration: '0:05'
     title: '5 minute break'
   - duration: '0:30'
-    slug: toot-your-own-horn-the-benefits-of-keeping-a-brag-doc-theo-harris
+    slug: tips-for-great-review-comments-cameron-shorter
   - duration: '0:10'
     title: '✋ 10 min Q&A'
   - duration: '0:20'

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 <a href="https://github.com/Datadog/documentation">documentation
-    repository</a>.</p>'
+    repository</a>.</p>
+
+    <p>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.</p>'
 - title: Creating truly accessible documentation
   slug: creating-truly-accessible-documentation-felicia-sephodi
   series: Write the Docs Australia
@@ -42,10 +46,53 @@
     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. </p>
-
-    <p>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.</p>'
+    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.</p>
+
+    <p>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.</p>'
+- 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
+  year: 2024
+  speakers:
+  - name: Cameron Shorter
+    slug: cameron-shorter
+    twitter: 
+    website: 
+  abstract: '<p>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. </p>
+
+  <p>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.</p>
+
+  <p>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.</p>
+
+  <p>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.</p>
+
+  <p>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. </p>'
 - 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
@@ -66,56 +113,19 @@
     by both curiosity AND altruism. </p>\n<p>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. </p>\n<p>Some further enticing
-    bullet points (because if you can’t get meta in this context, when can you?!):
-    </p>\n<p>• 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.</p>\n<p>All the
-    answers? Definitely not. But it's always a good thing to throw around some questions!</p>"
-- title: 'Toot Your Own Horn: The Benefits of Keeping a Brag Doc'
-  slug: toot-your-own-horn-the-benefits-of-keeping-a-brag-doc-theo-harris
-  series: Write the Docs Australia
-  series_slug: australia
-  year: 2024
-  speakers:
-  - name: Theo Harris
-    slug: theo-harris
-    twitter: 
-    website: 
-  abstract: '<p>Ever been stumped in an interview when asked about your proudest achievements
-    from the last six months? Felt like your manager didn’t understand your contributions
-    during a performance evaluation? Struggled to celebrate your professional wins?</p>
-
-    <p>As working professionals, we often get so wrapped up in daily tasks that recalling
-    impactful work becomes difficult when needed. After experiencing this firsthand,
-    I volunteered to create and run a Brag Doc Working Group at my company. This initiative
-    aims to help my teammates and me better capture, reflect on, and celebrate our
-    professional achievements.</p>
-
-    <p>In this talk, we’ll cover:</p>
-
+    bullet points (because if you can’t get meta in this context, when can you?!):</p>
+
     <ul>
 
-    <li>The purpose of keeping a Brag Doc</li>
-
-    <li>Practical examples of what a Brag Doc can look like</li>
-
-    <li>The ups and downs of building a working group for your company</li>
-
-    <li>How your Brag Doc can be utilised as a professional tool in different contexts</li>
-
-    </ul>
-
-    <p>You''ll learn how to systematically document your achievements, making it easier
-    to communicate your value during reviews, interviews, and stakeholder meetings.
-    I’ll also share my experience in creating a supportive community around documenting
-    wins and how this practice can improve team morale and personal growth.</p>
-
-    <p>Join us to explore how a simple Brag Doc can become a powerful tool for your
-    professional success.</p>'
+    <li>Specific writing techniques taught in journalism school that can become
+    part of your technical writing skillset.</li>
+    <li>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. BONUS: How the above
+    can help you identify and ‘correct’ a particular feature of many AI-written documents.</li>
+    <li>What the research says about the link between emotions and understanding instructions.</li>
+    <li>Uncovering the best motivation to be a better technical writer.</li></ul>
+
+    <p>All the answers? Definitely not. But it's always a good thing to throw around some questions!</p>"
 - 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
@@ -155,17 +165,25 @@
     website: 
   abstract: "<p>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</p>"
+    these cases? Different business units may be siloed and have strong standards
+    and long-established conventions, and these standards often contradict.</p>
+    <p>A recent project at CSIRO developing IT naming guidelines has provided me 
+    with a template for any future such projects.</p>
+    <p>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:</p>
+   <ul> 
+    <li>Prescriptive rules vs. loose guidance</li>
+    <li>Overall consistency vs. necessary differences in approach
+    between business units</li>
+    <li>Grandfathering existing practice vs. starting fresh</li>
+    <li>Meaningfulness and searchability vs. uniqueness (e.g. including IDs in names)</li>
+    <li>Detailed guidance vs. quick reference value</li>
+    <li>Addressing current project scope vs. later scalability to organisation-wide guidelines</li>
+    </ul>
+   <p>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. </p>"
 - title: Snack Videos for your Audience
   slug: snack-videos-for-your-audience-ruth
   series: Write the Docs Australia
@@ -177,18 +195,24 @@
     twitter: 
     website: 
   abstract: "<p>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.</p>
+    <p>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.</p>"
+    can snack video instead of eating a meal.</p>
+
+    <p>In this talk, I will cover the following:</p>
+    <ul>
+    <li>Reasons behind our approach with looking at how different generations learn
+    and the importance of learning accessibility. </li>
+    <li> Explore the video foundations, such as scripts, as it is still important 
+    to have written words. </li>
+    <li>Look at the learner’s mental models and how bite-sized learning can be easily digested.</li>
+    <li>Give an overview of the production process that you can implement.</li></ul>
+
+    <p>And finally, it is showtime and we will watch 2 short videos.</p>"
 - 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
@@ -209,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.</p>
+
+    <p>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.</p>
 - title: Brick Docs Workshop
   slug: brick-docs-workshop-yvonne-perkins
   series: Write the Docs Australia
@@ -309,4 +341,5 @@
     people disappear like the switchboard operators of old? Will there be a "Write
     the Docs" conference next year, in 5 years, in 10?</p>
 
-    <p>Without "skin in the game" Gerry is neither a true believer in AI nor a denier of its potential, and is perhaps in a good position to offer a view from the sidelines of the maelstrom.</p>'
+    <p>Without "skin in the game" Gerry is perhaps in a good position to offer a view
+    from the sidelines of the maelstrom.</p>'

docs/conf/australia/2024/news/tickets-closing-get-ready.rst

@@ -0,0 +1,54 @@
+:template: {{year}}/generic.html
+
+.. post:: October 22, 2024
+   :tags: {{shortcode}}-{{year}}, tickets, visiting, sponsors
+
+Get ready for Write the Docs Australia 2024
+============================================
+
+We're just over 4 weeks out from the conference, and we hope everyone is getting excited!
+
+Read on to see what's coming.
+
+Ticket sales closing soon
+--------------------------
+
+We will be closing ticket sales **Saturday, 16th November**, so if you've been on the fence, now is the time to buy one!
+
+If you were hoping to come to this years event,
+we recommend that you `get your tickets soon <https://www.writethedocs.org/conf/australia/2024/tickets/>`_.
+
+Things to prepare for
+---------------------
+
+* **Read the Visiting Melbourne information**. Our `Visiting {{city}} <https://www.writethedocs.org/conf/{{shortcode}}/{{year}}/visiting/>`__ page contains all the information you need for finding food, transit, and other things to do while you're in town.
+* **Review the schedule.** The `Schedule page <https://www.writethedocs.org/conf/australia/{{year}}/schedule/>`_ has the latest and most complete information about the presentations. This is where we will also update any changes/cancellations if they occur.
+* **Review the Code of Conduct.** We have a wonderful community full of diverse and amazing people. We expect everyone to behave in a respectful manner at all conference events and online channels. Our `Code of Conduct <https://www.writethedocs.org/code-of-conduct/>`_ has all the information.
+
+Get involved at the conference
+------------------------------
+
+-  **Attend the Brick Docs workshop.** This year, similar to our last few conferences, we will have a workshop on Day 1 after the lightning talks.
+   The workshop is free for all conference attendees.
+-  **Plan an unconference session.** We’ll be running the `Unconference <https://www.writethedocs.org/conf/australia/2024/unconference/>`__
+   both days. Want to chat with like-minded folks about a very specific thing? This is the place. We’ll have a sign-up board
+   so you know what’s happening, and supplies to help you brainstorm.
+-  **Plan a lightning talk.** We’ll have `Lightning Talks <https://www.writethedocs.org/conf/australia/2024/lightning-talks/>`__
+   each day after lunch. These are 5 minute presentations and a lot of fun. They can be about anything you want. This is your chance to
+   share something you are passionate about with the audience. Slides    are not required.
+-  **Join us at the Thursday night social.** This is an event just for conference attendees, held on *Thursday evening from 5pm-7pm*, with free snacks and drinks. It will be held at The Oxford Scholar (427 Swanston St, Melbourne) with good non-alcoholic beverage options, as well as alcoholic. 
+
+Thanks so much to all our sponsors
+----------------------------------
+
+We are so grateful to have our sponsors help in bringing these events to life every year.
+
+Thanks so much to the following companies for supporting the Australia conference this year:
+
+.. datatemplate::
+   :source: /_data/{{shortcode}}-{{year}}-config.yaml
+   :template: {{year}}/sponsors-simplelist.rst
+
+We're excited to see all of you soon, and can't wait to share a wonderful few days with you in our online space.
+
+The Write the Docs team