Technical Writing & Communication Resources
Jan 26 2022
🏟️ Organizations #
▶️ Videos #
🌐 Sites #
Stuff that pertains to other industries and specialties.
🎙️ Journalism #
⚖️ Intellectual Property #
IP is actually kinda funny, you gotta write clearly, but without giving away too much detail. Some spoofing is in order…
🖥 DevRel #
The difference between a software developer and an engineer is that engineers document their stuff.
API Docs I Like #
No better teacher than good examples, because we should always copy and steal from the Old Masters.
- Structure is direct and straightforward
- Not too many animations
- Tables are clean (unlike some monstrocities that span the horizontal width and have 3+ columns for some reason)
- No collapsing menus in the body content (easy to Ctrl-F)
- I find it interesting that they hide the scrollbar and the fact that it’s 1 gigantic page. Hmm 💡?
🛸 Professional Software #
This list contains software for business use, compared to the open-source/personal stuff listed on the Writing Tools page. Each piece of software has a special niche, and you don’t have to use everything, however it’s good to know the special advantages of a software.
Text Editors #
A simple text editor is important for those times when you really just need to jot something down, and you don’t need fancy styles.
| Conventions | |
|---|
| Markdown | Simplistic, quick, human-readable plain text. |
| Asciidoctor | Plain-text for authoring technical layouts. |
| rST | reStructured Text for Sphinx and Python-based docs. |
In general, HATs are the flagship tools of the trade, specifically designed to organize technical manuals and reusable segments. This style of composition is called topic-based authoring, and alternatively the tool may be known as a CCMS. They allow setting variables for output targets, “programming” which tailors a written product to many audiences and consumption channels.
💡 Knowledgebase #
While HATs can be used to create a knowledgebase (KB), KB style is suited for customer support, which assumes a less expert audience, and typically hosts more multimedia outputs (videos, interaction, diagrams, learning material) besides the usual PDF or article.
Wikis are another… strange hybrid. It’s like a knowledgebase or cloud storage, but usually private, and sometimes you want to share with guests. They elicit a “yikes” from me. Kind of a necessary evil.
| Wiki | |
|---|
| Confluence | JIRA integrated wiki and notes repository. Free if under 10 users. |
| SharePoint | Integrated with OneDrive and hosts wiki/intranet portals. |
| Notion | A note-taking and sharing system. Has a free tier. |
| Nuclino | Similar to Notion. |
| Guru | Cheatsheet style cards, works well with Slack chat. |
📰 Design and Publish #
Crossover into graphic design and communication with visual mediums.
| General | |
|---|
| Canva | Pre-made templates for print and social media. |
| Adobe Photoshop | Flexible and used for all kinds of graphics. |
| GIMP | It’s not as good as Photoshop for things like mockups, but it’s free. |
| Physical | |
|---|
| Adobe InDesign | The current industry standard for print. Excellent control over typography and layout. |
| Scribus | It’s almost as good as InDesign for the unbeatable price of free. |
| MS Office Publisher | Casual tool if you’re not a full-blown graphic designer. |
| Digital | |
|---|
| Snagit | Screen-capture tool that lets you add arrows, blurs and callouts. |
| Adobe Illustrator | An excellent program for creating clean illustrations for print or web, and even animations. |
| Inkscape | A free program with a similar niche to Illustrator, but has poorer CMYK (print ink color) support. It’s better for creating SVG. |
| UI/UX | |
|---|
| Sketch | Shining paragon of UI/UX composition, but Mac-only requirement is limiting. |
| Axure | Has advanced interaction capabilities for high-fidelity demos. |
| Figma | A free collaboration platform offered by Google. |
| Adobe XD | Similar to the above. |
| Balsamiq | Wireframe designer, low-fidelty and UX focused over UI. |
📌 Business Process #
The stuff that you need to make your point (slide decks, demos).
A lot of people use MS Office PowerPoint / Google Slides to create flowcharts, since they have templates and can insert shapes, but they’re not as good as dedicated diagramming programs.
| Management | |
|---|
| Aeon Timeline | If you’re a paralegal, you probably need something like this. |
| JIRA | Product development management used in a lot of enterprises. |
| Trello | A lighter version of JIRA. |
| Asana | Similar to Trello. |
Outlook #
If you’re entrenched in the Microsoft Windows ecosystem and use Outlook for email…
The Desktop Sticky Notes app syncs with the Notes section of your Outlook client. It’s pretty handy.
Typically Zoom, WebEx and conference software have an inbuilt recording feature, but for extra polish you may need additional programs.
| Video Recording | |
|---|
| OBS Studio | Open-source, for recording and streaming. |
| Camtasia | Beginner-friendly screen capture program. |
| Post-processing | |
|---|
| Kdenlive | Open-source, free video editor. |
| Olive | An up-and-coming video editor aimed at the professional market. Still in beta but usable. |
| Davinci Resolve | Professional-grade video editor made by Blackmagic Design with a free and pro version. |