Hacker News new | past | comments | ask | show | jobs | submit login
Advent of Technical Writing: Placeholders (jamesg.blog)
28 points by zerojames on Dec 13, 2023 | hide | past | favorite | 8 comments



I'm coming at this from way, way, waaayyy outside the lanes of a software tech writer, but in hardware CCS (component content system) architectures like S1000D, it's not just the XML elements and attributes that are fixed. It also has a system of module addressing, where each module is represented by a code called a DMC (data module code), and that DMC - by itself - has enough data encoded inside it that it serves as a pretty good placeholder by itself.

One example would be like so:

  DMC-SUPERPLANE-DEMO-E28-32-01-03A-280A-A
So I know this is a data module, for the SUPERPLANE product, the variant is DEMO, the E tells me this is for AVEE (air vehicle engine and equipment), 28 is fuel, 3X is dump, so 01 must be something in the fuel dump system. 03A says it's three levels down in an assembly, and 280 is an Inspect procedure.

So yeah - pretty good placeholder. Except.

There's a whole other discussion about how using it like this is the precisely wrong way to employ S1000D DMCs.

As BMoD (later ASD, later AECMA) envisioned it back in the late 1980s (yes!), the DMC would be created by a godlike Systems Engineering group working hand in hand with a Logistics group, and as they flowed down, the writers would dutifully fill in the blanks in this magical structure. In the real world of today, everyone ignores SEs, no customer pays for Logistics past initial issue, so DMCs get hacked through by Level II writers[1] with absolutely no training whatsoever, creating a gigantic trainwreck of tens of thousands of DMCs.

The trainwreck is caused, in no small part, by the spec's assumption that the task analysis is already finalized. THAT is why the DMC SNS "top level domain" after Product and SDC is Function, not zonal, not assembly, not task. But that's another very long story. Oh, look, another trainwreck.

We're not even going to touch the fact that you can dream up your own DMC schemes. In the words of one memorable officer: "For a specification, it doesn't do a very good job of specifying things"

[1] And I have some stories about Level 2 writers in this business. You'd think everyone knows what a scroll wheel is in this year of 2023, but you would be wrong.


When I am writing technical content, I often use placeholders while I'm writing, to stay focused.

I asked around and it turns out a lot of other documentarians do, too! I thought I'd write about this in case anyone finds it helpful!


I use this trick too.

It's conceptually similar to Python's pass keyword or leaving a TODO comment about some feature that you'll eventually need to implement but don't need to bother with at this very moment.


Yes indeed!

P.S. I love https://technicalwriting.tools.


I was classically trained to add `TK` meaning “to come” (sic.) as a placeholder. Allegedly the letter combo TK very rarely occurs otherwise.

Wikipedia article —

https://en.m.wikipedia.org/wiki/To_come_(publishing)


> Allegedly the letter combo TK very rarely occurs otherwise.

Interesting!


Thank you for this neat little trick. Going to use this for Webdesign when I transition the loremipsum blocks to content where info is missing/unclear. [ask client]

Love the written by a human sticker


Thank you! Little tricks like this help me stay focused. Technical writing involves enough context switching already -- referring to docs, past articles, research papers, etc. To the extent I can minimize unnecessary context shifting, I do.

All credit goes to https://notbyai.fyi/ for the design of the "not by AI" sticker. I know it is symbolic, but it is personally meaningful to me.




Join us for AI Startup School this June 16-17 in San Francisco!

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: