Hacker News with Generative AI: Technical Writing

How to Grow as a Technical Writer (passo.uno)
We all want to do a good job. Some of us also want to get better at our craft for a number of reasons, either practical or slightly delusional. Those include getting a raise, strengthening our résume, or simply ending the day with a fragile feeling of satisfaction after surviving failure for the nth time. They’re all good goals, though the ways of achieving them are not always straightforward.

Technical Writing, Career Development, Writing, Self-Improvement

11 points by theletterf 5 days ago | 1 comments

Don't Use ISO/IEC 14977:1996 Extended Backus-Naur Form (EBNF) (2023) (dwheeler.com)
If you need to define a language (such as a programming language or complex data structure) it’s often helpful to use some kind of Extended Backus-Naur form (EBNF). Often people do a Google search, find out that there’s an ISO/IEC standard (ISO/IEC 14977:1996), and then just use it... without realizing that this very old ISO/IEC standard has a lot of problems and should not be used.

Programming Languages, Software Development, Standards, Technical Writing

50 points by gslin 6 days ago | 38 comments

Embeddings are underrated (2024) (technicalwriting.dev)
Machine learning (ML) has the potential to advance the state of the art in technical writing. No, I’m not talking about text generation models like Claude, Gemini, LLaMa, GPT, etc. The ML technology that might end up having the biggest impact on technical writing is embeddings.

Machine Learning, Technical Writing, Embeddings

483 points by jxmorris12 11 days ago | 150 comments

Docs like code in basic terms (deborahwrites.com)
Most guides to docs like code, even the ones for non-devs, assume you have some developer knowledge: maybe you're already using version control, or you've encountered build pipelines before, or you're working alongside developers.

Technical Writing, Documentation, Software Development

66 points by DeborahWrites 18 days ago | 60 comments

MathML with Pandoc (leancrew.com)
Since switching from MathJax to MathML to render equations here on ANIAT, I’ve tried several approaches to generate the MathML.

MathML, Pandoc, Technical Writing, Math Rendering, Web Development

58 points by goranmoomin 20 days ago | 11 comments

My $6k Advance as a Self-Published Technical Author (mtlynch.io)
I just received $5,947 in advance sales for my first technical book, even though it’s only 25% complete, and I’m self-publishing it. The book is called Refactoring English, and it’s a guide for software developers to improve their writing.

Self-Publishing, Technical Writing, Software Development, Finance

44 points by mtlynch 27 days ago | 6 comments

Teach, Don't Tell (2013) (stevelosh.com)
The purpose of technical documentation is to take someone who has never seen your project, teach them to be an expert user of it, and support them once they become an expert.

Technical Writing, Documentation, Education, Software Development

212 points by Tomte 68 days ago | 75 comments

Rules I Learned About Technical Writing (thecoder.cafe)
As you may know, in 2022, I published my first (and last) book, 100 Go Mistakes and How to Avoid Them. While I had already been maintaining a technical blog for more than a decade, I learned a ton during this experience. Here are ten rules I learned about technical writing while writing my book.

Technical Writing, Programming, Books, Go

9 points by mooreds 86 days ago | 0 comments

The Seven-Action Documentation Model (passo.uno)
I think all technical writers, at some point or another, feel the urge to base their work on something more systematic than “it’s just the way folks documented stuff since forever”. Toolkits and frameworks provide content types, which is immensely valuable when you know what you want to write, but starting from there is like buying a hammer without knowing that half of the work you’ll do is turning screws.

Technical Writing, Documentation, Software Development, Frameworks

96 points by remoquete 134 days ago | 10 comments

Oral History of Caroline Rose, Writer of Inside Macintosh (ycombinator.com)
Caroline Rose was a technical writer at Apple from 1982, lead writer and editor of "Inside Macintosh".

Oral History, Apple, Technical Writing, Macintosh

14 points by msephton 140 days ago | 4 comments

Myst Markdown – Markdown for technical/scientific document (mystmd.org)
MyST is an ecosystem of open-source, community-driven tools designed to revolutionize scientific communication.

Markdown, Technical Writing, Scientific Communication, Open Source

195 points by gmgn 141 days ago | 43 comments

Why your team needs a Technical Writer to manage your documentation (momorell.com)

Technical Writing, Documentation, Software Development, Teams

9 points by mooreds 147 days ago | 1 comments

Making Screenshots of Test Equipment Old and New (tomverbeure.github.io)
Last year, I create Fake Parallel Printer, a tool to capture the output of the parallel printer port of old-ish test equipment so that it can be converted into screenshots for blog posts etc.

Software, Hardware, Retro Computing, Screenshots, Technical Writing

134 points by zdw 175 days ago | 26 comments

Your docs are your infrastructure (stackoverflow.blog)
Fabrizio Ferri-Benedetti, who spent many years as a technical writer for Splunk and New Relic, joins Ben and Ryan for a conversation about the evolving role of documentation in software development.

Technical Writing, Software Development, Documentation

25 points by runos 178 days ago | 18 comments

Embeddings are underrated (technicalwriting.dev)
Machine learning (ML) has the potential to advance the state of the art in technical writing. No, I’m not talking about text generation models like Claude, Gemini, LLaMa, GPT, etc. The ML technology that might end up having the biggest impact on technical writing is embeddings.

Machine Learning, Technical Writing, Embeddings

367 points by misonic 204 days ago | 176 comments

What docs-as-code means (passo.uno)
I’ve recently started a new job as a documentation engineer. While my work is largely the same as that of a technical writer, the sound and semantics of my new job title gave me some pause and made me think about what it really means to be doing docs-as-code. To say that it’s about writing documentation using the same tools and methods as software developers is correct, but fails to acknowledge the full consequences of the fact.

Software Development, Documentation, Technical Writing, Workflow

102 points by remoquete 215 days ago | 113 comments

Focus on decisions, not tasks (technicalwriting.dev)
In technical communication, we don’t talk much about decision support; we talk about task support… In many cases, the information people need to complete their tasks is not information on how to operate machines, but information to support their decision making… simply documenting the procedures is never enough… What I am talking about is documenting the context, letting users know what decisions they must make, making them aware of the consequences, and, as far as possible, leading them to resources

Technical Writing, Decision Making, User Experience

298 points by kaycebasques 217 days ago | 61 comments

I Landed 4 Jobs and Earned $25K+ with Technical Writing (catalins.tech)
As a final-year university student preparing to enter the industry, I knew I had to differentiate myself from other candidates in a competitive job market. That's when the idea struck me: what if I combined two activities I enjoy, programming and writing?

Technical Writing, Career Advice, Job Hunting, Programming

20 points by caminmccluskey 225 days ago | 2 comments

LaTeX Style Guide for EE 364B [pdf] (2014) (web.stanford.edu)

LaTeX, Technical Writing, Stanford University, EE 364B, Course Materials

120 points by walterbell 229 days ago | 31 comments

Technical writing is too important to leave to language models (counting-stuff.com)
There are no shortcuts to writing something worth reading

Technical Writing, Language Models, Artificial Intelligence

16 points by articsputnik 244 days ago | 0 comments

Ask HN: Technical Writing Resources (ycombinator.com)

Technical Writing, Resources, Writing, Ask HN

11 points by stevenking86 276 days ago | 5 comments

There is no mystery over who wrote the Blue Screen of Death (microsoft.com)