Writing Day¶
Each year we run an event called the Writing Day during the conference. This event is modeled after the concept of sprints, which are common in open-source conferences. The main premise is 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.
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.
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.
Schedule¶
- Date & Time: Sunday, May 19th, 9am-5pm, with the conference opening reception in the same space until 8.
- Location: Crystal Ballroom, 1332 W Burnside St. We will be in the main ballroom.
Writing Day this year is sponsored by Asciidoctor. Thanks for your support!
Projects¶
Get Started with AsciiDoc¶
Writing Day sponsor Asciidoctor will maintain a presence throughout the day, eager to support documentarians interested in creating great docs with the Asciidoc markup language. Whether you’re already passionate about open source, eager to add a valuable skillset, or just curious, experts in documentation platform development and technical writing with AsciiDoc will be available for tutoring, workshops, and demos:
Play with AsciiDoc
You do not have to come with a mission or any sense of commitment. Come to Writing Day, let us learn what you’re up to and maybe show you some stuff.
Convert your docs or get started with AsciiDoc
Take advantage of AsciiDoc consultants and practitioners to get a head start on migrating to AsciiDoc-based tools or just kick-start a project.
Learn docs-as-code basics
We realize not every documentarian has a firm grasp of the docs-as-code approach, what makes it special, and the basic technical hurdles, such as understanding dynamic markup, using code editors, and managing source code with Git. Asciidoctor volunteers are happy to bring you up to speed on the broader docs-as-code approach, even if you don’t already have an interest in AsciiDoc. We will meet you at your level and have exercises for learning the ins and outs of popular tools.
We are maintaining a GitHub project for all our Write the Docs programming. We would love to engage with you there, get feedback on our ideas, and hear how we can make Writing Day more successful for you!
Make Microsoft Docs More Inclusive¶
Make our Microsoft Docs more inclusive; focusing on underrepresented groups and gender neutrality.
- People to contact: Cory Fowler and Doug Erickson
TensorFlow.org¶
TensorFlow.org [https://www.tensorflow.org] is Google’s open source machine learning platform and one of the most popular projects on GitHub. The website documentation is the primary way that developers learn about TensorFlow and, many times, their first experience with machine learning and AI.
Technical docs are pulled from GitHub [https://github.com/tensorflow/docs] so you’ll need a GitHub account. Markdown experience helps, as well as basic familiarity with Jupyter notebooks [https://jupyter.org/] (since many of the guides [https://www.tensorflow.org/alpha/tutorials/quickstart/beginner] can be run and edited in the browser [https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/r2/tutorials/quickstart/beginner.ipynb] using Colab). API reference docs [http://bit.ly/ml4all-docs-sprint] are built from Python docstrings in the TensorFlow source code [https://github.com/tensorflow/tensorflow].
Read the TensorFlow documentation contributors guide [https://www.tensorflow.org/community/contribute/docs] for workflows and set up. And if you have questions before Writing Day, feel free to ask on the TensorFlow docs mailing list [http://bit.ly/tf-docs-list] or the Gitter channel [https://gitter.im/tensorflow/docs].
Write CockroachDB Docs¶
CockroachDB is the SQL database for building global, scalable cloud services that survive disasters.. Here’s a quick overview video: https://www.youtube.com/watch?v=VgXiMcbGwzQ
Here are a few ways you can contribute to the CockroachDB docs:
Test our docs
Give us feedback about clarity, correctness, helpfulness, and ease-of-use by:
- User testing our Search
- User testing our Authorization docs
Improve our current docs
If you love fiddling around with a new product, you can:
- Improve existing docs by adding missing details or correcting errors
- Fill gaps in our existing docs. If you’d like to dig deeper, we’re missing docs on a handful of important features.
- Make an easy edit. This is great for those who want to try Git and open their first PR.
Note: Our docs live in GitHub, so you’ll need a GitHub account.
…
Feel free to go through the full list of GitHub issues labeled wtd-writing-day and claim the ones you want to work on. And of course, we (@laurenh, @jseldess, and @rmloveland) will be available throughout the day to help out. Also feel free to reach out to us if you have questions or suggestions in the interim. See you on Writing Day!
Netlify CMS - Give Feedback and Write Docs¶
Netlify CMS is an open source CMS for static site generators, created by the folks at Netlify. It works with content stored in Git repositories, so it’s great for adding an editor UI to docs-as-code workflows.
We’re a really friendly and active community, happy to answer questions in Gitter chat, Netlify Community, or even Write the Docs Slack. (Try #static-site-generator or ping @verythorough!) We uphold the Contributor Covenant Code of Conduct, and we work hard to make sure all contributors feel welcome, supported, and recognized.
Try it out¶
You can visit the live demo to play around with a basic version of the editor UI, but for the full tour, we recommend cloning a sample site. That way, you can see how your edits in the UI generate commits and pull requests on the connected repository. The featured starter templates use Gatsby, Hugo, and Middleman, but you can use Netlify CMS with almost any static site generator or build tool.
Talk to us about your docs-as-code needs¶
While Netlify CMS can be used for all sorts of content, we’re focused on making it really great for docs. Come visit the Netlify CMS table, and we can give you a tour of how things work, chat about your docs-as-code workflow, and get your feedback and feature requests.
One of our big projects right now is making Netlify CMS capable of managing community contributions to open source docs, so if you have an open source documentation project you’re working on, we’d love to hear about it!
Help write the docs!¶
If you’re ready to dig into some writing, we’ve tagged several issues to help get you started:
- Improve contributing guidelines, including documentation-specific guidelines and adding a style guide.
- Write a guide for setting up Netlify CMS with your favorite site generator. You can start by following one of the existing guides, then follow that pattern with a new one. Copyediting for existing guide is also appreciated.
- Create a UI guide for content editors.
- Add a Requirements & Installation doc for developers interested in adding Netlify CMS to their sites.
- Add documentation for the editor UI markdown widget.
Jessica (@verythorough in Slack) and Kristen will be there from the Netlify docs team, as will Benaiah, full-time maintainer of Netlify CMS. We’ll be happy to answer questions and collaborate. We look forward to meeting you!
Help improve MDN Web Docs¶
MDN Web Docs is a source of references, guides, and tutorials on standards-based web technologies, much loved by web developers. It was chosen as #1 for Documentation in the Developer’s Choice Awards for 2018, conducted by SlashData.
Yet, MDN Web Docs needs help from documentarians—–whether you are a programmer, designer, or someone else who cares about web technology. MDN is a wiki, so anyone can contribute to content. We have tasks for you to help with content about accessibility, or web performance, or with making sure our most-accessed pages are up to editorial standards. If there’s another area of web technology that you’re passionate about documenting, we welcome that too!
GitLab - Meet the Docs Team and Contribute to the Docs¶
GitLab is an open core single application for the entire software development lifecycle. From project planning and source code management to CI/CD, monitoring, and security.
Our documentation is open source and everybody can contribute to it. All the content is hosted on GitLab.com, so you will need a GitLab.com account.
You can contribute to our docs by:
- Taking a look at the issues labeled with writingday::proposed.
- If you don’t find something you’d like to work on, view all issues labeled ‘Documentation’ and ‘Accepting Merge Requests’ or browse the docs and find something else you’d like to improve (and log it in a new issue).
- Once you find the issue you want to work on, add a comment mentioning @gl-docsteam to inform us that you’re working on this for Writing Day (and tell us in person!).
- Create a merge request with your proposed changes.
Once your merge request is reviewed and merged, it will appear on the docs site shortly!
If you have any questions, you can reach to us in person or in Slack: @axil, @evan.read, @miketechnically.
Your project here¶
Send us a pull request or an email talking about what you want to work on!
