Has AI tells(theconsensus.dev)
126 points by 7777777phil | 106 comments
A Consensus blog post by Phil Eaton about a small detector for AI writing tells, used to help promote good technical writing.
#technical-writing on Hacker News
21 stories tagged technical-writing, newest first.
The Wild West of polyglot docs sites(technicalwriting.dev)
11 points by zdw | 1 comments
Blog post on technicalwriting.dev about the challenges of building docs sites that unify API reference output from multiple languages' documentation generators.
Anti-patterns in software blogging(refactoringenglish.com)
289 points by ilreb | 141 comments
Michael Lynch's Refactoring English article cataloguing common mistakes beginner software bloggers make, such as meandering intros and overreliance on links.
Tech Needs Humanists More(passo.uno)
62 points by eigenBasis | 73 comments
Blog post on passo.uno arguing that tech writers should study humanities and languages rather than coding or AI to stay valuable in the AI era.
Diátaxis(diataxis.fr)
510 points by ryanseys | 57 comments
Homepage of Diátaxis, a systematic framework for technical documentation organized around tutorials, how-to guides, reference, and explanation.
Why senior developers fail to communicate their expertise(nair.sh)
742 points by nilirl | 314 comments
Essay by Tuhin Nair on why senior software developers struggle to communicate their expertise to others.
Do your own writing(alexhwoods.com)
690 points by karimf | 222 comments
Blog post by Alex Woods arguing against using LLMs to write documents and essays, since writing is a way to think and build trust.
I canceled my book deal(austinhenley.com)
583 points by azhenley | 326 comments
Blog post by CMU professor Austin Henley explaining why he canceled his book deal for a book on challenging programming projects.
Examples Are the Best Documentation(rakhim.exotext.com)
372 points by Bogdanp | 137 comments
Blog post by Rakhim arguing that concrete examples are the most useful form of technical documentation and are often missing from official docs.
How I, a beginner developer, read the tutorial you, a developer, wrote for me(anniemueller.com)
782 points by wonger_ | 363 comments
A humorous blog post parodying how developer-written tutorials full of jargon read to a non-developer beginner.
Writing a good design document(grantslatton.com)
509 points by kiyanwang | 130 comments
An essay by Grant Slatton giving advice on how to write a good software design document, prompted by a question from a friend on Twitter.
Why I wrote the BEAM book(happihacking.com)
577 points by lawik | 144 comments
A Happi Hacking blog post in which the author explains why they wrote The BEAM Book, a book about the Erlang virtual machine.
Embeddings are underrated (2024)(technicalwriting.dev)
441 points by jxmorris12 | 133 comments
An essay arguing that text embeddings are an underrated machine learning tool, especially for technical writing and documentation work.
The Story Behind “100 Go Mistakes and How to Avoid Them”(thecoder.cafe)
352 points by Kerrick | 106 comments
Teiva Harsanyi's Coder Cafe post recounting the process behind writing his book "100 Go Mistakes and How to Avoid Them."
How to write blog posts that developers read(refactoringenglish.com)
533 points by rbanffy | 148 comments
A chapter from Michael Lynch's Refactoring English offering advice on writing blog posts that software developers will actually read.
Sell yourself, sell your work(solipsys.co.uk)
391 points by ColinWright | 152 comments
Colin Wright's essay arguing that technically brilliant work is wasted unless you write it up clearly and communicate it to others.
Diátaxis – A systematic approach to technical documentation authoring(diataxis.fr)
460 points by OuterVale | 109 comments
Homepage of Diátaxis, a framework for technical documentation that organizes content into tutorials, how-to guides, reference, and explanation.
I prefer rST to Markdown(buttondown.email)
320 points by BerislavLopac | 379 comments
Hillel Wayne's Computer Things newsletter post arguing that reStructuredText is preferable to Markdown for writing books and documentation with Sphinx.
Writing about what you learn pushes you to understand topics better(addyosmani.com)
597 points by twapi | 149 comments
Addy Osmani blog post arguing that writing about what you learn deepens understanding and reveals gaps in your knowledge.
Some tactics for writing in public(jvns.ca)
475 points by hasheddan | 165 comments
Julia Evans blog post sharing tactics she uses to make reader comments on her public writing more useful and less annoying.
Just Simply – Stop saying how simple things are in our docs(justsimply.dev)
391 points by cbracketdash | 250 comments
JustSimply.dev is an essay urging writers of technical documentation to stop describing things as "simple" or "easy" because it alienates readers who are struggling.