Writing Day¶
What is Writing Day?¶
Writing Day is modeled after the concept of “sprints” or “hackathons”, which are common in open-source (OSS) conferences.
Held on Sunday, the first day of the conference, attendees are encouraged to bring a project or contribute to someone else’s project.
The main goal is to get interesting people in the same room, sharing their passion and goals and collaborating to find creative solutions to solve a problem or issue.
Attendees are invited to submit their project pre-conference! It’s a great way to get other attendees excited about contributing. We’ll open project submissions in February/March.
There are two main types of Writing Day attendees:
- Project leads: Attendees bringing ideas, content, or OSS projects to work on with contributors.
- Contributors: Attendees looking to contribute to various content projects.
Here are examples of projects that you might see at the conference:
- Open-source software documentation
- General documentation writing
- Best practices manual (for your company, or the world)
- Resume, cover letter, and portfolio reviews
- Blog posts
- Tips and tricks
- Great works of fiction
- Love letters
- The Documentarian Manifesto
If you find specific examples helpful, check out the Portland Writing Day 2023 project list.
Writing Day Schedule¶
Date: Sunday, April 14, 9am-5:00pm PST
Writing Day is an all day event that is designed with flexibility in mind. Feel free to check out as many projects as make sense for you and your schedule!
- Morning Introduction: The coordinator welcomes everyone and gives a Writing Day overview.
- Project announcements: Project leads are invited to give a 2 minute project summary.
- Session 1: Projects and co-working begins.
- Lunch Break
- Project announcements: Project leads are invited to give a 2 minute project summary, starting with the afternoon-only projects.
- Session 2: Projects and co-working reconvene.
- Writing Day ends at 5:00pm.
Exact times to be posted on our Schedule page.
Logistics¶
Come prepared with the following tools:
- Laptop, tablet, or other device
- GitHub account (you may also want a GitLab account)
- Text editor of your choice for coding or content creation
Lead a Project¶
Leading a project at Writing Day is a wonderful opportunity to engage with documentarians from a variety of backgrounds, experience, and expertise. Their collective wealth of experience can help upgrade your documentation and create a more inclusive project. This empowers all of us to work together to create opportunities for each other and bigger, better communities.
Tips to create and lead a new project effectively:
- Provide a project overview with a specific focus or goals: Your project overview is a 2 minute pitch that describes your project and clearly defines a focus area or goal. Here’s a good example from Writing Day 2022, the Open Web Docs project.
- Pre-label tasks and issues: Create a specific event label and label documentation tasks and issues. This empowers new contributors to find tasks that interest them.
- Create a task filter: This helps contributors find issues more easily and see which issues have been assigned.
- Clear onboarding: Ensure your ReadMe, contribution guidelines, or onboarding instructions are accurate and up to date.
- Submit your Writing Day Project: Adding your project to the Writing Day project list promotes your project to our attendees before the event. Many attendees have told us that their curiosity about certain projects incentivised their attendance.
- Project Experts: We recommend having 1-2 project experts on your project. We love our developer advocates, community managers, and subject matter experts! You’re welcome to call for virtual reinforcements from your community as well.
- Flexibility and Understanding: Reminder that attendees may need additional info to be successful in onboarding to your project.
These are suggestions and not requirements. It is perfectly valid to show up to Writing Day, tell us about your project day of, and ask for volunteers! It’s been done before and it will be done again.
Contribute to a Project¶
Writing Day is the perfect opportunity to learn about new projects and technologies. Some attendees stay at one table all day, others table hop. Do what feels right to you.
Check out the project list! Keep in mind that some attendees choose to announce their projects during Writing Day and the information is not available on the project list.
Tips to contribute to a project:
- No matter your experience level, you are welcome! We are glad you’re here. Even if you feel as though you don’t have the right skills or experience or have never attended an event like Writing Day before, you’ll be surprised how much you can share.
- Check out our guide to writing documentation. Our beginners guide will help you get started, and give you some ideas for how you can contribute to a project.
- Ask people for help if you have a question. If at any time you get stuck with new concepts and tools, you are in a room full of friendly people from diverse backgrounds and experiences. If you are not sure who to ask, ask the Welcome Wagon or Registration staff or volunteers. We will help you find someone!
Call for Project Submissions¶
Based on the positive response to Writing Day during Portland 2023, we strongly recommend that you submit your Writing Day project in advance! Projects submitted by March 28, 2024 are promoted in our pre-conference Writing Day blog post and email.
Learn more in our Call for Project Announcement.
As usual, walk-on projects are always welcome. All attendees always have the option to bring a project, sign up on site, and announce it during Writing Day.
If you need additional information to advocate for Writing Day in your community or organization, see the Convince Your Community resource.
Project List¶
Docs as Tests & Doc Detective: Help us test your docs!¶
Project organizer Manny Silva, he/him.
Doc Detective is back at Writing Day again, this time with our friends, Docs as Tests. Does your project or product have a UI? APIs? SDKs? We can help you test them and keep your docs accurate.
Docs as Tests is a tool-agnostic strategy for validating doc content by performing documented tasks directly in your products using automation. By validating that doc contents work as written, you can:
- Prevent broken docs.
- Ensure consistent UX between docs and products.
- Build user trust.
Our Writing Day goal is to test at least 10 docs sets! We want every writer to be confident in their docs.
Come by our table, and we’ll help you set up Docs as Tests with whatever tools (such as Doc Detective) or strategies (like unit testing code snippets) are appropriate. Establish a zero-trust relationship between your docs and product, catching bugs in both as you go.
Mutual Aid for Tech Writer/Documentarian Job Hunters¶
Coordinated by Kenzie Woodbridge, they/them.
Let’s help each other get ready for our job searches! Are you thinking of applying for a new or different tech writer/documentarian jobs and would appreciate feedback on your resume? Or, are you responsible for hiring and know what you’re looking for in a resume and application?
Let’s get together and offer each other some feedback on the important documentation we’re using to move our careers forward.
Meet the new GitBook (Sponsor)¶
Project organizer Addison Schultz, he/him.
Our mission at GitBook is to help you harness your team’s knowledge!
Our Writing Day goal is to teach you how to use your team’s internal knowledge to the fullest. Documenting internal knowledge is often the last task in a sprint and most likely to be skipped or forgotten. This leads to knowledge gaps that can slow the progress towards your team’s ultimate goals and reduce efficiency. GitBook is here to help you combat the knowledge gap and make docs effortlessly epic!
That’s not all, GitBook is bringing three Writing Day challenges. No matter your experience level, these challenges are designed to guide you through the tasks necessary to publish your first, but hopefully not last, GitBook knowledge site! The content on your knowledge site is up to you, it can be documentation, a company knowledge base, or something to help you plan the rest of your sprint. GitBook staff will be around to answer any questions you have.
Writing Day challenges:
- Publish your first site with GitBook
- Install the Slack Integration and capture your first snippet
- Import your docs from an existing repo or an open source project
It gets better! For every challenge completed, you’ll receive one (1) entry for our raffle to win an epic swag box! That means if you complete all 3 challenges, you’ll get three (3) entries. More information about the raffle entry is available during each session.
Already familiar with GitBook? We’re looking for people like you to brainstorm features as. Help us make the ultimate documentation platform!
Use OpenAPI with the Museum API¶
Project organizer Heather Cloward, she/her. The Museum API was built by Redocly for educational purposes.
The Museum API is a sample OpenAPI description. It offers a set of endpoints to interact with a museum’s services – such as retrieving museum hours, managing special events, and purchasing tickets.
Our Writing Day goal is to onboard contributors and improve the Museum API definition. Help us create more complex use case examples like discriminator, webhooks, oneOf, allOf, etc.
The Museum API was built specifically to teach OpenAPI concepts and to create a better developer experience. The more realistic and complex the Museum API is, the better it can demonstrate all that OpenAPI has to offer.
Write the Docs Documentation Salary Survey¶
Project Organizer Kay Smoljak, she/her. Afternoon only session.
The WTD Salary Survey has been running annually since 2019, with the goal of identifying appropriate salary ranges and providing a basis for pay negotiations. It has sparked discussions on other topics such as remote work, pay transparency, and job satisfaction.
The 2023 results - which will be announced before Writing Day - are drawn from the largest respondent pool yet, and for the first time include structured as well as freeform feedback on the survey itself.
Our Writing Day project centers on updating the survey site content and question text on GitHub. We’ll go over the:
- Constraints of the project.
- Feedback we have received.
- Areas we think are most in need of attention.
Our Writing Day goal is to improve the clarity, inclusivity, neutrality, and relevance of the questions, the instructions, and the general flow of the survey. The format, questions, and instructions have evolved each year, based on the submitted responses and feedback from the community, but it’s largely been a one-person effort.
We’re particularly interested in:
- Better catering to contractors, freelancers and self-employed people.
- Addressing potential privacy concerns.
- Exploring ways to expand the respondent base.
This is where we need you the most! Everyone who works in documentation is a subject matter expert on this topic, and we want your ideas on how to make the survey better benefit the community as a whole.
Tabletop game rules writing workshop¶
Project Organizer Ryan Macklin, he/they. Afternoon only session.
Tabletop game rules are a neat and weird form of technical documentation!
If you’re working on writing tabletop game rules or are interested in learning about that, join me during the Writing Day afternoon session. You can bring your own work-in-progress rules documents, and I’ll have some work-in-progress rules as well.
The purpose for this Writing Day workship is to help:
- Technical writers turning their craft toward game rules writing
- Tabletop game writers understand that their skills are applicable to technical writing as a career
Note: This is not a game design or playtesting session, purely a session about helping one another with the difficult task of rules writing.
More projects coming, get excited!
Contact Us¶
Email us at portland@writethedocs.org with any questions.
