Writing Day

Writing Day

Write the Docs has an event called the Writing Day, modeled after the concept of sprints from the open source world. The idea is simple: to get a bunch of interesting people in a room together and have them work towards shared goals.

To make the most out of the Writing Day, we recommend that you either come with a project, or be ready and willing to contribute to someone else’s project.

Here are some examples of projects that you might want to work on:

  • Open source software documentation
  • General documentation writing
  • Best practices manual (For your company, or the world)
  • Blog posts
  • Tips and tricks
  • Great works of fiction
  • Love letters
  • The Documentarian Manifesto

You get the idea.

All this adds up to a room full of smart people sharing your problems, your passion, and your goals. So be ready to learn some new things and to teach others what you know.

Even if you feel as though you don’t know that much, we know you have a lot to offer. Come surprise yourself with how much you can share.

Logistics

Please bring a computer or some other mechanism with which to create written words.

We’ll be creating and editing content, so make sure that you have the tools you need to contribute.

Writing Day Schedule

8:30

Doors Open, Breakfast Served

9:30

Writing Day Introduction - Introduction to Sprints & Project Introductions

10:00

Team up and start working

12:30

Lunch Break

18:00

End of Writing Day, Beginning of Reception

20:30

End of Reception

Documenting a new project?

Check out our beginners guide to writing documentation. This should help you get started, and give you some ideas for how you can contribute to a project that you love.

Write Write the Docs on Writing Day

This year we’re also running a session where you can help improve your favorite website. Yup, you can brainstorm improvements, write helpful content and posts, or just magically improve Write the Docs.

If you’re writing text to add to the website, ideally you’ll already be familiar with GitHub and writing in plain text (markdown or restructured text), but we’ll be there to help out if you’re not.

If you’d rather brainstorm a content reorganization in Google Docs, improve our python scripts or our jinja templates we’ve got plenty to do there as well.

Here are a few things we’ll be working on on writing day, reach out to @plaindocs or @meker if you have any questions or more suggestions.

Brainstorm user oriented architecture

The website is currently organised around meetups, conferences, guides, etc – find ways to introduce user-oriented labels considering audience. Who is coming to the site, why? What are the goals of the site?

  • Learn about docs
  • Get involved with the community
  • Attend conference
  • Submit a conference proposal
  • Find a video of a talk that I saw

Improve navigation

Let’s discuss information architecture – can we organize the content better? Provide better navigation?

Write articles for the newsletter

Summarize content from the Slack channel for the newsletter.

Help develop the Documentation Guide

Help reorganize the guide content, or write and edit topics. Check out Documentation Guide ahead of time and bring your ideas to the table!”

Fix website issues

We have a list of issues on GitHub tagged as writingday that includes things like

  • fix broken links (we have a lot of these)
  • improve the meetup pages
  • make a better video archive
  • add list of conference write ups for past conferences

Kubernetes

If you’re looking to contribute to open source documentation on Github during Writing Day, you’ll have the opportunity to edit content for Kubernetes. Kubernetes is an open source system that manages containerized applications across different infrastructures.

The Kubernetes doc folks are looking for help to edit content, get it into templates, and verify that it conforms to their new site architecture. No previous product experience is necessary to help out, and they pay in swag, gracious thanks, and enthusiastic high-fives. Docs are located at Kubernetes.io and they’re pulled directly from Github.

Detailed instructions

OpenStack

It’s great to learn about open source contribution in a friendly, welcoming environment like OpenStack. OpenStack offers a collection of projects for cloud services such as compute, storage, and networks. Yes, it’s large, but we have some maps for contributors who like to work with and build clouds.

OpenStack documentation tools, tests, and processes are the same as the Python code processes for all projects. The source is in RST and the docs build with Sphinx using scripts run in a virtual environment with the tox command line tool. The source control system is git, and the review system is gerrit. The source files are in the project repos and a docs-only repo, openstack-manuals. The documentation sites are:

You can find all the instructions for contributing to documentation in the OpenStack Docs Contributor Guide, including a comprehensive style guide and a quick start guide for first timers. Recently the team members added a section about contributors who speak English as a second language. There’s also a comprehensive, collaborative set of translation tools.

The bug tracking system is in Launchpad. For example, go to the bug tracker for the openstack-manuals project, and search for doc bugs that are tagged with low-hanging-fruit and also unassigned.

There are REST API docs with specific contributor information, administrator docs, user docs, a variety of developer docs, and tools upon which to work. With a Facebook login (sorry, yes, we want to improve that gated access), you can try using an OpenStack cloud at https://trystack.org. Go see what you can learn about collaborating on a large set of open source cloud projects.

MediaWiki

Team up with other volunteer tech writers and contribute to the documentation for MediaWiki, the open source software powering Wikipedia . We are looking for help with various types of tasks such as improving the technical documentation of articles, re-organizing content, verifying documentation, and writing tutorials on how to use or install a service. If you’re interested, you can prepare ahead of the writing day: