Open source docs: where does the money come from?
Open source docs don’t come for free. So who’s paying for it?
ddbeck.com
Writing by Daniel D. Beck
Latest posts
Where do open source docs go?
To start publishing open source docs, you need somewhere to put them. Here are some common approaches.
5 things I know about automating docs with GitHub Actions
Get ahead of some confusion, if you're starting out automating your docs workflow with GitHub Actions.
Plausible substitutes for dirty lucre
How to calibrate technical writing rates when your client has a limited budget.
Write like a caveman
Break a style block with a little help from our ancestors.
A guiding principle for marking up documentation for accessibility
Reconcile your documentation’s visual styles and accessible markup.
Customize Markdown conversions with Pandoc
Learn to fine-tune Markdown conversions with Pandoc.
Questions to ask yourself before freelancing as an American abroad
Know whether you’re ready to start down the path of living abroad and freelancing.
The Wayback Machine is not your portfolio
It’s time to own your own portfolio.
Networking for introverts, imposters, and frauds
How do you connect with others and find work if you’re too introverted?
Stop throwing away opportunities to introduce yourself
Working remotely or in a hybrid setting, it can be extra hard to be noticed and valued as a member of a team. How do you make yourself seen?
“Starving for docs”: the open source docs portfolio myth
Tech writers get advice to use open source to build their portfolios, but it leads to frustration. Here's what you should consider instead.
A list of fictitious numbers, domains, and more
Avoid using real credit cards, phone numbers, IP addresses, domains, and postal codes with this list.
Don’t blur screenshots if you want to keep your secrets
Blurring isn't the the way to protect personal information.
Better-than-Grep tools for writers and developers alike
Searching docs-as-code files doesn’t have to be slow and frustrating.
4 ways to keep PDF docs off Google search results
If you’re stuck serving PDF docs, consider these ways to improve search results.
What does “deprecated” mean to your readers?
When a feature is on its way out, the terminology doesn’t matter.
When is it safe to use “new” in technical documentation?
Some tech writers say never write “new”, but it’s safe to use if you understand its power.
Git reflogs don't have to be scary
Git gives you lots of tools to escape bad situations. Why are they all so cryptic?
4 ways to keep distractions out of your screenshots
Sick of contorting to keep irrelevant elements out screenshots? Here are four tips to help.
Should you use the first-person plural in your documentation?
Most style guides say that, no, we're not in this together after all.
What do you say to “no one reads the docs”?
You need a way to respond with confidence that creates an opening for real understanding.
The second person is OK in developer documentation (but don’t take my word for it)
Style guides are unanimous on this one thing.
Three ways product and feature names get mixed up in your writing
Names change, become forgotten, or never were. How do you keep your content consistent?
Scheduling content with static site generators and automatic deployments
There are lots of ways to schedule future content with a static site generator. Here’s how I do it with GitHub Actions and Netlify.
Felt trite might delete later: the hows and whys of avoiding clichés
Some ideas to help you avoid clichés in your business or technical writing.
How small is too small to launch new docs?
How much is enough to launch? A question that haunts writers when there are no external deadlines.
Think habitat, not ecosystem, when you choose a static site generator
If a static site generator’s ecosystem is an ocean, then you might join a happy school of fish or become chum for the sharks. Think about your niche before diving in.
When notes aren’t enough: how to record subject-matter experts
Overcome the awkwardness and get permission to record your next meeting
The 30-minute information rescue
No follow up questions please: what to do when only get once chance to talk to a subject matter expert
What's the difference between a function and method?
An attempt at clearing up a common point of confusion.
Acute Strategies
I made a strange little productivity game inspired by the Pomodoro Technique, Brian Eno, and “Zen and the Art of Motorcycle Maintenance.”
Pay the Docs: pay transparency at Write the Docs Portland
How can people who write the docs understand their and their peers' compensation better? I moderated a discussion to find out.
Checklists for public speaking
Checklists are a great way to deal with nerves before public speaking.
Meeting invitations for people who hate meetings
Better meetings start with better meeting invitations.
How I helped Mozilla turn documentation into data
Mozilla asked me to work on a project: turn documentation into data. When is documentation better off as data?
Stop excluding your audience
Avoiding exclusionary language can keep your audience on your side.
The Feedback Matrix
I have a rubric for evaluating feedback on written content.
Five reasons you need an editor
Everyone’s a critic, so don’t make it easy for them to be critical.
How to replace a Kindle 2 battery
Give a Kindle 2 a new lease on life by replacing a degraded battery.
Documentation is artificial experience
The best documentation is a shortcut through time.
Don’t be so negative
Instructions with conditions can be hard to write clearly. Here are a few tips to make them easier to understand.
Writing feature requests and bug reports that get results
You can make a strong case for bug reports and feature requests, if you get organized.
Setting expectations in step-by-step directions
Step-by-step directions work best when you give your reader a way to gauge success or failure.