This page intentionally left blank. ⬇️, ➡️, or spacebar 🛰 to start slidedeck. --- class: middle, center # Writing for Technology --- # What is Technical Writing? For the purposes of this resource, I am speaking primarily about open source projects and ways in which you may want to contribute to them other than code-writing. This may extend out a bit beyond traditional "Technical Writing," so I tried to better contextualized as "Writing for Technology." I am thinking of this as a presentation more like "How to contribute to open source projects as a person who does not write code" but that title is too verbose to be catchy! Many of these things are crucial to a project's success, though, and I hope they provide useful avenues towards humanizing open source technology. --- # What is Technical Writing? 1. communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations; 2. communicating through technology, such as web pages, help files, or social media sites; 3. providing instructions about how to do something, regardless of the task's technical nature. [Source - Society for Technical Communication](https://www.stc.org/about-stc/defining-technical-communication/) --- # Why is Technical Writing important? - Documentation is important! - Supports open source projects - Helps share and promote your work --- # Things you can do (for your project) - Documentation (in general) - Installation guide - FAQ - Use cases - License - Contribution guide - Code of conduct - Style guide - Accessibility guide - Promotional material --- # Documentation Obviously! This is the biggest and best thing you can do, and there's always plenty of work to do. I guess all of the later points I'm about to make are all considered "documentation." --- # Documentation guidance [writethedocs.org](http://writethedocs.org) "Write the Docs is a community of people focused on software documentation. We consider everyone who cares about communication, documentation, and their users to be a member of our community. This can be programmers, tech writers, customer support, marketers, and anyone else who wants people to have great experiences with software." --- # Installation guides A great place to start is making sure a project has thorough installation instructions for all supported operating systems. Why is this plural? An installation guide should cover how to use and install for an end-user (and may differ between operating systems, don't forget!), but there should be an installation guide (or guides) that specifically articulate to get something set up in the context of software development, for future potential contributors. --- # FAQ Writing an FAQ can help users get access to the knowledge they need more quickly and without having to dig through pounds and pounds of documentation text. --- # Use Cases I find use cases serve multiple purposes: 1) they help the end-user understand how they might fit in and use software and 2) help fully expand on and articulate existing software features. It's a good way to fully understand the software better and potentially uncover gaps in understanding or obscure features that can be improved. --- # License Does your project have a license yet? If it does, is it prominently placed and well-understood by users? If the answer to the above is "no," you have some work to do! A lot of this work will involve researching difference licenses, making pro/cons for which to use and why, and gathering consensus from everyone involved with the project. --- # Contribution guide Drafting a contribution guide is a good task that can help drive people to participate in your project. It helps people understand the general rules of the project, which usually are not articulated. This is a place to write about or mention/reference coding styles, writing styles, commit and pull request styles, and how to get a local environment set-up. On GitHub, if a Contributing.md file is added to the root of the repository, users opening new Pull Requests will be notified. --- # Code of Conduct Although I recommend not writing your own Code of Conduct and rather adapting one, like [Contributor Covenant](https://www.contributor-covenant.org/), because experts have put a lot of work into ensuring this covers the needs of a project that you might not have anticipated. On GitHub, if a Code of Conduct is added to the root of the repository, users filing new Issues will be notified before posting. --- # Style guide If you're working on a project for a long time or coming into a larger project, it's a good idea to draft a style guide (or adopt one) to dedicate to a project. This way, everyone knows the best and consistent ways to write. Style Guides can be for code, for human-language writing, for design, for accessibility, or all of the above. [18F Open Source Style Guide](https://open-source-guide.18f.gov/) --- # Accessibility guide Speaking of which, researching and drafting accessibility guidelines can help steer the project and remind developers of their obligations to make material on the web available to *everybody*. - [18F Accessibility Guide](https://accessibility.18f.gov/) - ["A Practical Starter Guide on Developing Accessible Websites"](http://journal.code4lib.org/articles/12697) - [Accessibility for Justice](http://www.inthelibrarywiththeleadpipe.org/2017/accessibility-for-justice/) - [WCAG Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/) --- # Promotional Material Finally, projects need to hype themselves just in a basic way. This is different from writing general documentation, which probably does include an introduction to the project, what it does, what needs it meets, and its goals. This is worded in a snappier way, for people that may need something "higher level" than the already-high-level introduction to a project. Some people think of this as "Executive Summaries" or "What I give to my bosses so that they understand what this is." --- ## Additional Resources - [awesome-writing (resources list)](https://github.com/jenniferlynparsons/awesome-writing) - [beautiful-docs](https://github.com/PharkMillups/beautiful-docs) for examples - [Engineer's Guide to Technical Writing: What is technical writing?](https://www.asminternational.org/documents/10192/3448649/ACFAA62.pdf/5890813c-31ba-46b4-b7fa-8f20eb03fb6e) - [How to write high quality friendly documentation that people want to read](https://github.com/jamiebuilds/documentation-handbook) - [WriteTheDocs Documentation Guide](http://www.writethedocs.org/guide/) --- ## Learning more [Home](/)