├── LICENSE ├── retrospectives.md ├── README.md ├── write-for-us.md └── resources.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Gareth Dwyer 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /retrospectives.md: -------------------------------------------------------------------------------- 1 | # Makers' Retrospectives 2 | 3 | There is a growing tradition in the overlapping communities of Makers, 4 | [open startups](https://hackernoon.com/what-does-it-mean-to-be-an-open-startup-f4446984189), 5 | and [solopreneurs](https://www.merriam-webster.com/dictionary/solopreneur) to write retrospetives at regular intervals. 6 | 7 | These retrospectives may be daily, weekly, monthly, or yearly, or some combination of this and look back at recent progress, 8 | comparing it to goals, and analysing what went right and what could have gone better. 9 | 10 | Here are some makers whose retrospectives I have enjoyed (in alphabetical order). Please add your own via a pull request! 11 | 12 | * [Michael Lynch](https://mtlynch.io/retrospectives/) ([twitter](https://twitter.com/deliberatecoder)) 13 | * [Jesse Szepieniec](https://jessems.com/my-january-2020-retrospective/) ([twitter](https://twitter.com/jessems)) 14 | * [Pat Walls](https://www.starterstory.com/stories/starter-story-story) ([twitter](https://twitter.com/thepatwalls)) 15 | * [Cory Zue](http://www.coryzue.com/writing/) ([twitter](https://twitter.com/czue)) 16 | * [Aaron Taylor](https://atay.me/posts/april-in-review/) ([twitter](https://twitter.com/TheAaronTaylor)) 17 | * [Gareth Dwyer](https://sixhobbits.github.io/hugoblog/posts/2020-q1-retrospective/) ([twitter](https://twitter.com/sixhobbits)) 18 | * [Allison Seboldt](https://allisonseboldt.com) ([twitter](https://twitter.com/allison_seboldt)) 19 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Technical Writing 2 | 3 | For some reason, there are only a relatively small number of people who are interested in both technology and language. If you are one of them, technical writing can be a great profession, or means of generating a side income. 4 | 5 | This repository is a collection of technical writing resources. Pull requests to add more resources are highly encouraged. 6 | 7 | ## Writing Resources 8 | 9 | [Technical Writing Resources](./resources.md) is a list of books and other resources to help you become a better technical writer 10 | 11 | ## Publishing Resources 12 | 13 | [Publishing Resources](./write-for-us.md) provides information on where you can publish your technical posts, and who will pay you for them. 14 | 15 | ## Retrospectives 16 | [Retrospectives](./retrospectives.md) is a list of makers and solopreneurs who write retrospectives on their businesses and progress. Although not directly technical writing, these people tend to be interested in both writing and building technical projects, and offer good examples of technical writing in their other posts too. 17 | 18 | 19 | ## About 20 | I have been writing technical articles on a freelance basis for a number of years. I'm always surprised that while there are thousands of posts and resources out there relating to helping you become a better (programmer|founder|data scientist|anything else) there is very little about technical writing, and many people don't even know that technical writing is a thing that exists and that pays. 21 | 22 | This is my little attempt to fill that gap. I plan to extend it in future with information about publishing companies and writing tools. If you have suggestions for more sections, or want to add to existing sections, please submit a pull request. If you're not comfortable with git, [Tweet at me](https://twitter.com/sixhobbits) with your suggestions or use one of the other contact options at the bottom of [my website](https://dwyer.co.za). 23 | 24 | 25 | 26 | 27 | -------------------------------------------------------------------------------- /write-for-us.md: -------------------------------------------------------------------------------- 1 | # Write for us 2 | 3 | A collection of places to publish your writing, with a focus on those that pay for content. 4 | 5 | Once you've honed your technical writing skills with the collection of resources [here](./resources.md), you'll want to start getting your writing out there where people can read it. A common way to start is by creating a Blogger, Wordpress or equivalent page, writing a hello world post, posting another article a week or so later, maybe one more a month later, get discouraged by the fact that you have no viewers, and then an article every 6-12 months starting with "I haven't written on here in a while because...". 6 | 7 | While writing for free for the community is noble, writing is a valued skill, and you can get paid for it. If you write for established companies, you get money and you reach more people, as these companies usually have existing blogs that have an established readership base. Also, by committing to write for a place that pays you, the quality of your content will improve. You'll try harder, and often the company will have an editor go over your work and improve it before publishing. 8 | 9 | # Places that pay for writing 10 | Here's a collection of places looking for freelance technical writers. The going rate is usually about $200 per post. 11 | 12 | ## [Twilio Voices](https://go.twilio.com/twilio-voices/) 13 | Twilio pays $500 per published post. Tutorials have to contain code, and writers are encouraged (but not required) to make use of Twilio services for their tutorials. 14 | 15 | ## [Digital Ocean](https://www.digitalocean.com/community/get-paid-to-write) 16 | Digital Ocean pays writers $300 to write about Python or JavaScript projects or to write tutorials showing how to install and use software (for example, installing Apache2 on Ubuntu). They match the payout with a charitable donation. 17 | 18 | ## [WonderProxy](https://wonderproxy.com/blog/looking-for-authors/) 19 | WonderProxy focuses on automated testing and pays up to $500 for technical tutorials in this area. 20 | 21 | ## [LWN](https://lwn.net/op/AuthorGuide.lwn) 22 | LWN produces articles on Linux and free software. They pay $300 to new authors, but this can be increased for regular authors. There is some related discussion [in this HN thread](https://news.ycombinator.com/item?id=23920240). 23 | 24 | ## [FusionAuth](https://fusionauth.io/blog/) 25 | FusionAuth accepts contributions of 1000-2000 word technical blog posts. They pay $500/post and you get the byline. 26 | They have a number of client libraries ( https://fusionauth.io/docs/v1/tech/client-libraries/ ) and have a pressing need to to get blog posts outlining how to use each one. They're also happy to discuss other possible topics such as OAuth, how to use tokens to protect APIs or integration with a particular CMS. You can reach out to them at marketing |at| fusionauth.io. 27 | 28 | ## [Honeybadger.io](https://www.honeybadger.io/blog/write-for-us/) 29 | Honeybadger is an exception monitoring service which pays writers $500/post. The posts are usually about larger computing topics as they apply to Ruby development. For example, "Everything about character encoding for Rubyists." They do occasionally feature posts about languages other than Ruby. Posts are usually 1500-2500 words and should include code. They don't have to relate to Honeybadger's business of exception monitoring. 30 | 31 | ## [LogRocket](https://blog.logrocket.com/become-a-logrocket-guest-author-7d970eb673f9/) 32 | LogRocket offers up to $300 for topics focussed on front end development, for example React, Redux, Vue.js, webpack, Wasm, MobX, GraphQL, JavaScript, Frontend development best practices, Product/UI/UX design. 33 | 34 | ## [ClubHouse](https://clubhouse.io/clubhouse-write-earn-give-program/) 35 | ClubHouse pays between $350 and $600 and publishes blog posts and tutorials aimed at more senior people: "with a particular focus on engineering leads, managers and VPs/CTOs." 36 | 37 | ## [Linode](https://www.linode.com/docs/contribute/) 38 | Linode is a VPS host that offers up to $300 for technical tutorials relating to Linux. 39 | 40 | ## [Vultr](https://www.vultr.com/docs/vultr-docs-program-guidelines) 41 | Vultr is a VPS provider similar to DigitalOcean and Linode that offers up to $300 for articles on server administration and applications. 42 | 43 | ## [Smashing Magazine](https://www.smashingmagazine.com/write-for-us/) 44 | Smashing Magazine is a longstanding publication that publishes all types of articles for app and web developers and designers. They advertise rates of $200 USD per post. 45 | 46 | ## [FloydHub](https://blog.floydhub.com/write-for-floydhub/) 47 | FloydHub publishes technical tutorials on data science, AI, and ML. They are known to pay $150 per article in USD or platform credits. 48 | 49 | # Writing for exposure 50 | 51 | If you can string sentences together and know a bit about tech, your writing is worth something. However, sometimes it's worthwhile writing for exposure, especially if you haven't written much and you want a portfolio to show off when you pitch to places that pay. Here are some places where you can write for exposure. 52 | 53 | ## [CodeMentor.io](https://www.codementor.io/) 54 | CodeMentor is a mentoring platform where you can get paid by the hour to help people out with issues they face while coding. If you create a profile with codementor, you can publish technical posts and associate them with your profile. CodeMentor promotes selected articles on their main page every day, and this is a good way to get more mentees. You can also apply to write for their blog or community more formally, in which case they'll provide you with an editor to help all the way from outlining through to publication. 55 | 56 | ## [Dev.to](https://www.dev.to/) 57 | DEV is a community of software developers getting together to help one another by sharing helpful content in the form of technical posts, videos and in general helpful discussions. You can publish your content directly once you create a profile or crosspost content from your personal blog if you've got one. The community is welcoming and friendly so it's a great place to grow and get exposure. 58 | 59 | -------------------------------------------------------------------------------- /resources.md: -------------------------------------------------------------------------------- 1 | # Technical Writing 2 | There are a number of resources relating to technical writing, scattered around the web and in print. This is a (growing) list of technical writing resources. Pull requests to add titles are encouraged. Please add the title and a brief summary following the style below. For articles that are available on the web, provide a link. 3 | 4 | ## Books 5 | *The following books are not all specific to technical writing. However, their advice on general writing definitely applies to technical writing as well.* 6 | 7 | ### 'On Writing Well: The Classic Guide to Writing Nonfiction' by William Zinsser 8 | Zinsser describes writing as a craft, comparing it to carpentry. He focuses on teaching you how to edit, claiming that first drafts are never good. The earlier chapters provide general writing and editing advice, while the later ones are topic-specific and cover travel writing, technical writing, memoir writing, etc. 9 | 10 | ### 'The Elements of Eloquence' by Mark Forsyth 11 | This book teaches the lost art of rhetoric in a highly entertaining fashion. Each chapter is an explanation -- containing many hilarious and self-describing examples -- of a simple rule to make your writing sound better and be more persuasive. You can read it cover-to-cover, or open it at random. 12 | 13 | ### 'On Writing' by Stephen King 14 | This book is half an autobiography of Stephen King and half writing advice. Although it is aimed more at fiction writers, the advice is generic and sound. The intimate descriptions of the hardships King went through before becoming a famous writer are inspiring. 15 | 16 | ### 'Trees, maps and theorems' by Jean-luc Doumont 17 | Doumont runs training courses on scientific and technical communication. His book, subtitled 'Effective communication for rational minds', is aimed at technical people who want detailed and practical advice about how to communicate clearly. It does this in a highly structured way with plenty of examples. Later chapters also give advice on presentations, graphical displays and posters. It's also an obsessively edited book. Each minimalist double-page spread has one column of body text and three other columns for common questions, illustrations and examples –– and if you look closely you'll see that the paragraphs have been tweaked to be perfectly rectangular. 18 | 19 | ### 'Style: Toward Clarity and Grace' by Joseph M. Williams 20 | A slightly older book but still very worth a read. William's strength lies in identifying and naming what it is about difficult sentences that actually makes them difficult for humans to parse. The book starts at the level of individual sentences, walks through plenty of examples of how to polish them for maximal clarity, and later moves onto showing how to build coherent paragraphs and larger bits of text. 21 | 22 | ### 'Practical Typography' by Matthew Butterick 23 | Formatting and layout of text on a page or screen is an area of writing that's often overlooked or thought of as "someone else's job". However, with the modern prevalence of independent web publishing, where the writer and typographer will often be the same person, it's useful to know the basics of good typography. In describing their typography, Butterick also covers concepts valuable to technical writers such as effective emphasis and how to best present lists and hierarchies of headings. 24 | 25 | The book is available online only at http://practicaltypography.com/ -- as payment, Butterick encourages a donation or a purchase of one of his excellent fonts. 26 | 27 | ### 'The Sense of Style: The Thinking Person's Guide to Writing in the 21st Century' by Steven Pinker 28 | Linguist Steven Pinker takes an analytical approach to writing in this style guide, with chapters about reverse-engineering good prose, seeing the grammatical trees in sentences in order to untangle them, and how a writer's intimate knowledge of a subject may distort their writings about it (the biggest problem with much academic and technical writing). Much time is also spent investigating the rules of English grammar and dispelling the many myths that have grown up around it. 29 | 30 | ### 'Technical Blogging' by Antonio Cangiano 31 | This book is, as you may have guessed from the title, specific to technical blogging. "Successful people often get recognition by teaching what they know. Blogging is a reliable path to do that, while gaining influence in the process." Unlike most of the others here, it doesn't focus as much on writing well, but more about how to set up a technical blog, how to promote it and how to find time to write. 32 | 33 | ## Articles 34 | 35 | ### 'Writing well' by Julian Shapiro 36 | 37 | A free handbook in five parts that covers what to write about and how to rewrite to be clear and succinct, [available online at julian.com](https://www.julian.com/guide/write/intro). 38 | 39 | ### 'How to Write with Style' by Kurt Vonnegut 40 | Vonnegut presents 8 concise rules. He reminds us to 'sound like ourselves' -- something which is perhaps more difficult but still important in technical writing. http://www.novelr.com/2008/08/16/vonnegut-how-to-write-with-style. 41 | 42 | ### Material.io's writing guide 43 | This aims at language use for user interfaces, but it has many nice rules with concrete, short examples for each. The sections on Tone and Punctuation are applicable to general technical writing. 44 | 45 | ### Essays on CIA writing 46 | This is an interesting, but not that useful, collection of essays about writing well. They are from 1962 and were originally classified, but have since been released. You'll find the usual "avoid the passive voice and jargon" type of advice. The original essays can be found here https://www.cia.gov/library/readingroom/docs/CIA-RDP78-00915R001400200001-3.pdf and a higher level write-up about them here https://www.muckrock.com/news/archives/2017/jul/14/cias-style-guide/ 47 | 48 | ### Writers Stack Exchange, The 'rules' of writing 49 | A crowd-sourced list of axioms and rules of writing, along with descriptions, thoughts, and examples. You can find the whole list at [https://writers.stackexchange.com/questions/761/the-rules-of-writing](https://writers.stackexchange.com/questions/761/the-rules-of-writing) 50 | 51 | ## Videos 52 | 53 | ### The Craft of Writing Effectively by Larry McEnerney 54 | Aimed at academics, but very generally applicable writing advice, and why everything you learnt in school is probably wrong. You can find it [here on YouTube](https://www.youtube.com/watch?v=vtIzMaLkCaM) 55 | 56 | ## Meta 57 | *Something as meta as writing about writing would not be complete without a meta section of its own. Here are some articles that already collect and describe other works on writing.* 58 | 59 | ### Good Plain English: The problem with writing manuals 60 | Nat Segnit discusses six books about writing. Nat gives some entertaining examples, some focused on contemporary American politics. http://harpers.org/archive/2017/03/good-plain-english/ 61 | 62 | 63 | 64 | --------------------------------------------------------------------------------