topic Re: Technical writing suggestions in Tech Talk

Technical writing suggestions

ericgeater — Wed, 17 Jul 2019 19:43:24 GMT

My writing process is all my own. I have not been trained in a preferred or suggested writing style, because very few would ever read my technical docs. But sometimes I get snagged when trying to find le mot juste to fit specific meaning in terminologies.

An example: I use the word "extant" to refer to things which are "in present or current use". I usually leave "production" as a term which describes a whole and fully operational system or appliance, and leave "extant" to describe processes, policies, or objects which run on that equipment. My due diligence review on prod equipment distinguishes "extant" policies, processes or objects from abandoned, incomplete, or untidy configurations.

My questions:

A) How do you like "extant"? I feel like "in use" doesn't capture the importance of a policy or object.

B) What formulas or stylebooks do you employ in your technical writing?

Re: Technical writing suggestions

dcontesti — Thu, 18 Jul 2019 03:25:26 GMT

@ericgeater wrote:

My questions:
A) How do you like "extant"? I feel like "in use" doesn't capture the importance of a policy or object.
B) What formulas or stylebooks do you employ in your technical writing?

So I personally thought "extant" meant "surviving" but I can see how it would work. Call me old fashioned (remember I am older than dirt) but I think I still prefer the word "operational".

As to formulas for tech writing, I really don't have a style book that I follow but have always tried to ensure that no matter who picks up the document, that they can read it, with minimal issues. This link provides some good tips for technical writing.

https://en.wikiversity.org/wiki/Technical_writing_style

MHOO

Re: Technical writing suggestions

Steve-Wilme — Thu, 18 Jul 2019 09:40:15 GMT

I'd suggest that you write to be understood and stick to the terminology in use within the organisation or organisations that you're writing for. Finding technical documentation which uses terms which are not commonly understood distracts from getting a good understanding quickly. I'm very much a believer in writing in plain English.

Re: Technical writing suggestions

denbesten — Thu, 18 Jul 2019 13:02:01 GMT

@Steve-Wilme wrote:
I'm very much a believer in writing in plain English.

Amen.

Hard to answer the original question without context (e.g. a sample sentence), but "existing", "installed", and "current" are all potential synonyms.

Re: Technical writing suggestions

AppDefects — Thu, 18 Jul 2019 13:31:58 GMT

@Steve-Wilme wrote:
I'm very much a believer in writing in plain English.

I agree. Even better if it's the Queen's English 😉 KISS!

Re: Technical writing suggestions

Shannon — Thu, 18 Jul 2019 14:24:11 GMT

A) How do you like "extant"? I feel like "in use" doesn't capture the importance of a policy or object.

The 1st thing 'extant' brings to my mind is 'Not extinct,' so I might use it only to talk about something that hasn't become obsolete.

When referring to what's presently being used / followed / applied, I'll use 'Existing' or 'Current,' perhaps with 'Production' and 'Operational' to describe the environment and functionality.

B) What formulas or stylebooks do you employ in your technical writing?

I haven't yet attempted to improve technical writing skills, and just ensure that what I write is clear & concise, grammatically correct, and contains no ambiguous statements that might leave room for misinterpretation.

In addition to what @dcontesti mentioned, you can also check this document.

Re: Technical writing suggestions

Early_Adopter — Thu, 18 Jul 2019 15:57:55 GMT

Extant will work well in anglophone countries, but maybe not so well elsewhere depending on factors...

Randall Munroe’s “Thing Explainer” is an incredible style guide for fitting into the globish meta-culture and very funny., and really worth taking to heart, after all more folks use English as a second language then first. 🙂

The only other thing I do is put semi colons on the end of bullet points in all but the last bullet point in a billeted list, which I add a fullstop(period) to. To the best of my knowledge this is nonsense, however it annotated someone a while ago, when someone else did it(from some sort of style guide) an started doing it after that motivated by a spirit of devilment...

Re: Technical writing suggestions

rslade — Thu, 18 Jul 2019 18:36:39 GMT

> ericgeater (Newcomer III) posted a new topic in Tech Talk on 07-17-2019 03:43 PM

> My writing process is all my own.

If it weren't, forensic linguistiics/stylistic forensics wouldn't work.

> I have not been trained in a preferred or
> suggested writing style, because very few would ever read my technical docs.

I don't think anyone has ever been "trained" in a technical writing style. In most
of the companies I worked for, along the way, the technical writers were just hired
on the basis of history degrees. (The English majors all went to work in HR.
Hmmmm ...)

> But sometimes I get snagged when trying to find le mot juste to fit specific
> meaning in terminologies.

Well, I wrote a dictionary, if that'll help ...

> An example: I use the word "extant" to refer to
> things which are "in present or current use". I usually leave "production" as a
> term which describes a whole and fully operational system or appliance, and
> leave "extant" to describe processes, policies, or objects which run on that
> equipment. My due diligence review on prod equipment distinguishes "extant"
> policies, processes or objects from abandoned, incomplete, or untidy
> configurations. My questions: A) How do you like "extant"? I feel like "in
> use" doesn't capture the importance of a policy or object.

I like extant. But I'm weird.

Thing is, you've got to tailor your writing style to your audience. And, not just
your style, but your vocabulary, too. (Gloria, who is one of the world's best
editors, says I have at least thre different and quite distinct writing styles.
Apparently I also have at least two quite distinct speaking styles, as well.) If you
are speaking to your peers, "extant" should be fine. If you are speaking to
customers, or low level techs, you pretty much have to aim at the lowest common
denominator, and go for "in use."

> B) What formulas or
> stylebooks do you employ in your technical writing?

Either a) none, or b) 2,000. I don't use any specific or formal style guides (and,
over the years, I have really come to *hate* the Chicago Manual of Style). But I
strongly recommend you get a broad exposure to technical writing, and read as
much general technical literature as you can. Then you can get a range of styles
you can choose from: http://victoria.tc.ca/int-grps/books/techrev/mnbk.htm

Oh, and I highly recommend "BUGS in Writing," by Lyn Dupre:
http://victoria.tc.ca/int-grps/books/techrev/bkbugwrt.rvw

======================
rslade@vcn.bc.ca slade@victoria.tc.ca rslade@computercrime.org
"If you do buy a computer, don't turn it on." - Richards' 2nd Law
"Robert Slade's Guide to Computer Viruses" 0-387-94663-2
"Viruses Revealed" 0-07-213090-3
"Software Forensics" 0-07-142804-6
"Dictionary of Information Security" Syngress 1-59749-115-2
============= for back issues:
[Base URL] site http://victoria.tc.ca/techrev/
CISSP refs: [Base URL]mnbksccd.htm
PC Security: [Base URL]mnvrrvsc.htm
Security Dict.: [Base URL]secgloss.htm
Security Educ.: [Base URL]comseced.htm
Book reviews: [Base URL]mnbk.htm
[Base URL]review.htm
Partial/recent: http://groups.yahoo.com/group/techbooks/
http://en.wikipedia.org/wiki/Robert_Slade
https://is.gd/RotlWB http://twitter.com/rslade
http://blogs.securiteam.com/index.php/archives/author/p1/

Re: Technical writing suggestions

ericgeater — Fri, 19 Jul 2019 19:41:10 GMT

I've enjoyed reading this thread. Thanks for the suggestions. I write simply when possible, though often it can be unavoidable if it's a complex topic that stays mired in jargon... and that may vary based on the need of the document.

I didn't cover the types of writing topics, but a configuration procedure would likely be more complex and technical than a DR playbook. Simple is best for the widest audience, agreed! For my question, it is about configuration procedures on a device or a computer, so the audience should already expect a technical subject matter.

Again, thanks much!