Technical Writing

259

Solutions

242

Contributors

Technical writing is any written form of writing or drafting technical communication used in a variety of technical and occupational fields, such as computer hardware and software, engineering, chemistry, aeronautics, robotics, finance, consumer electronics, and biotechnology. IT encompasses the largest sub-field within technical communication. The Society for Technical Communication defines technical communication as any form of communication that exhibits one or more of the following characteristics: "(1) communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations; (2) communicating through technology, such as web pages, help files, or social media sites; or (3) providing instructions about how to do something, regardless of the task's technical nature".

Share tech news, updates, or what's on your mind.

Sign up to Post

Hi,

Maybe I'm quibbling here...

But, which of the two options below is correct:
1. Click here for the customer-facing documentation on the public Wiki.
2. Click here for the customer-facing documentation in the public Wiki.

Thanks!
0
Technology Partners: We Want Your Opinion!
Technology Partners: We Want Your Opinion!

We value your feedback.

Take our survey and automatically be enter to win anyone of the following:
Yeti Cooler, Amazon eGift Card, and Movie eGift Card!

Hi,

Maybe I'm overthinking this one...

When I write an instruction set, my format is along these lines (made-up example), oversimplified:

To create an EE post:
1. Clock Ask a Question.
2. Fill in your title.
3. Select topics.
4. Write your post.
5. Click Submit.

But, what if there's only one step e.g.
To exit the application:
1. Click Logout.

Is my instinct correct that I'd be better off without numbering the single step:
To exit the application: click Logout.

Thanks,
Steve
0
Hi,

My document suite for a web app contains a HELPFUL HINTS doc, which provides general info about the application.

I need to list certain system requirements/restrictions. Right now, I have only one (min. browser width), but this list could grow over time.

What's the best title for this section?
System Requirements (As I said in the title.)
Limitations (Meh.)
???

Thanks,
Steve

PS-Hope I'm not overthinking here...I think part of my brain's still on the holiday weekend. :)
0
Hi,

I'm getting up to speed with using SnagIt for screen captures. I'm trying to add a text box with an arrow pointing to a component of the screenshot.

While I can type text into a whitespace area of the screenshot, it displays w/o a border.  So, I need to figure out how to add the border. If SnagIt could do it automatically, like MS Word does for text boxes, that would be great. In addition, what's the best way to add a red arrow?

Thanks,
Steve
0
Hello,

In  a web application, we have a horizontal area of the screen displaying various metrics. e.g. (scrubbed)

Temperature     Humidity     Wind Direction  Wind Speed  Barometer
        74                    53%                 SW                         10 MPH        29.86


It's not a toolbar or ribbon b/c it's display-only. Accordingly, is there a more concise name than "screen area"?  I suppose I could say "section", but I'm not thrilled with that word. :)

Thanks,
Steve
0
Hi,

I'm documenting a time field that displays (e.g) 10;42:38.496
where .496 is 496 thousandths of a second.

So, if I say
HH:MM:SS.xxx, which are the letters to use for xxx?

Thanks,
Steve
0
Hello,

What is the proper terminology for a horizontal area at the top of a screen that contains not only menu choices, but also other options (e.g. change password, configure screen layout, etc.) I can't truly call it a menu, so what works? Panel? Bar? Something else?

Unfortunately, I cannot provide a screenshot b/c the software's proprietary.

Thanks,
Steve
0
Hello,

I'm documenting a report that includes a dropdown menu for date selection. e.g.

Today
This Week
This Month
This Year
Custom Date Range


Is it correct to say:
Select your Date Range from the dropdown menu?

I ask b/c to me, a Date RANGE is when you specify a starting and ending date (e.g. 5/10/2017 to 5/16/2017).

If "Date Range" is not appropriate,what would be?

Thanks,
Steve
0
For years, I was taught, I saw and I wrote that the area in the lower right corner of the Windows UI was the System Tray or Systray.
I just looked at the Microsoft Manual of Style 4th Ed and it's now called the Notification area.  
Where can I file formal complaint?  This is a stupid change.

Ugggh.
1
Hello,

I'm documenting a web application where the only way to exist is to exit the active browser window (tab?) in which the app is running.

Which is better terminology?

"To exit this application, close the active browser window"
"To exit this application, close the active browser tab""
<Something else>?

However I state it, I want to make it clear that you should not close the entire browser. :)

Thanks,
Steve
0
[Live Webinar] The Cloud Skills Gap
LVL 4
[Live Webinar] The Cloud Skills Gap

As Cloud technologies come of age, business leaders grapple with the impact it has on their team's skills and the gap associated with the use of a cloud platform.

Join experts from 451 Research and Concerto Cloud Services on July 27th where we will examine fact and fiction.

Hi,

I need to include a screenshot of a table that's displayed in a web app. This table contains (e.g.) one row for each day YTD, so, currently, it would be over 100 rows. I don't want to include all rows in screenshot, maybe just the first ten.

Is there a standard "indicator" to show the reader that the screenshot is truncated that non-technical people will understand?  Thanks.
0
Hi:

I'm writing a user manual with step-by-step actions and I'm looking for a web site or blog or pdf that has best practices for using colors in callouts, documenting keyboard mouse actions, etc.
0
HI,
In a document, I'm showing the reader how to navigate to a particular screen "Add Users". Per existing style, (which I've inherited), I need to write something like:

User Portal --> Internal Users --> Add Users

But, I'd like to prefix this sequence with a single word. Would I say "Path"? "Navigation"? Something  else? e.g.

Path: User Portal --> Internal Users --> Add Users
Navigation: User Portal --> Internal Users --> Add Users

Thanks!
0
Hey everyone,

I am documenting a screen which supports a series of options (e.g. filter, sort, search, expand-a-field) that control the display of the data rows. Other options allow you do edit or delete data. Accordingly, I'm going to have two sections, along the lines of:

  1. Display Options
  2. Edit Functions

However, some of the rows have a column with the value "Display". :)  Accordingly, I want to avoid using "Display" in another context.

I hesitate to use www.thesaurus.com because it will spit out (or should I say "display" ;) ) a whole bunch of synonyms that have nothing to do with my context. Accordingly, I'm hoping one of you can suggest the right word.

Thanks,
Steve
0
Can someone point me to guidelines to be used for people who suffer from color blindness.
Colors and/or shades and/or shapes to avoid.
0
Hey everyone,

In the following sentence:

"This product is currently in Beta ,and will be released to all  customers in March."

Am I correct in capitalizing "Beta"?

Thanks,
Steve
0
I am higher secondary student and I want do many class works. Along with this work I have to write my assignment papers in which I cannot complete all my task works. I need much time to complete a single essay paper. So, I prefer to proceed with best online writing service. Does any one have idea about the best essay writing service?
0
Hey everyone,

Forgive the obtuse title. I'm trying to explain to users that they need to enter a code that can be 8 or 10 digits. Is the following correct?

"Enter the 8- or 10-digit activation code."

Is the hyphen after the number 8 correct?

Thanks,
Steve
0
I had this question after viewing Writing numbers of 1000 or more with decimals in technical documentation.

Hi again,

My API document (for a query), contains certain conventions I'm informally following:
- Numbers in a floating point calculation are written with a decimal place. (e.g. 100.0).
- Variable/object names in bold.

Accordingly, I plan to add a list of conventions. The question is, where to put it. This doc structure is as follows.
Query 1.
   Table of Input Data
   Table of Output Data
   Table of Error Message Formats
Query 2.
   Table of Input Data
   Table of Output Data
   Table of Error Message Formats
etc.
etc.

My gut feeling is to list the conventions one time, at the top of the document; however, in a large doc, if you're on page 35, do you really want to return to page 1 to remind yourself of the conventions? Maybe have a reminder at the beginning of each query or even each table?

Thanks.
0
[Webinar] How Hackers Steal Your Credentials
LVL 9
[Webinar] How Hackers Steal Your Credentials

Do You Know How Hackers Steal Your Credentials? Join us and Skyport Systems to learn how hackers steal your credentials and why Active Directory must be secure to stop them. Thursday, July 13, 2017 10:00 A.M. PDT

Hi,

In writing technical documentation (in this case an API guide:
If I need to write the number 1000, I like to write as 1,000

However, if I need to write 1000.0 or 1000.1, is the comma still stylistically correct. e.g
1,000.0
1,000.1

Thanks,
Steve
0
Please I need help in knowing what language of instruction is Ladoke Akintola University of Technology in Nigeria used and stated in the international handbook of university 2012/2013. I need this information to ascertain my eligibility as a proof for international English language proficiency requirement in Swedish University. Thank you.
0
I have a PC that is intermittently not displaying the Readability Statistics after a spelling and grammar check. To complicate things even more, the same document does display the statistics on another PC.

I've checked all the appropriate settings in the Proofing options and the language options and they are set correct which is why it works on some of the documents.

I'm not really sure where to go with this and am about ready to just image the machine (I have already done a complete uninstall/reinstall of Office).

Thanks!
1
I have an old time clock, ATRx Proxtime that my supervisor wishes to bring back and connect to her computer to keep track of payroll.  The clock has not been used in some time and the gentleman that set it up is no longer here.  The clock is connected to a long phone cord (seems to RJ-11, not RJ-45).  I have what appear to be several RS-232 adapters that connect to either RJ-11, or RJ-45.  Will configuration work?  Am I totally missing the boat on this?  Yes, the computer she wants to use has an RS-232 DB 9 port on it.
0
I wanted to know how I could get assistance with my resume as far as polishing it up as well as with creating  my best profile for LinkedIn?  I know there are services online for this, but I wanted to hear from someone whose actually had experience in this field.  The pros and cons of this service.  I noticed that is not much of a guarantee of such services.  My present job role is IT engineer...Cisco, VMware, Windows...
0
Hey everyone,
For the following sentence, which of the below is correct?

"You need write access to your CD-ROM drive to take advantage of this feature..."
"You need write access on your CD-ROM drive to take advantage of this feature..."
"You need write access for your CD-ROM drive to take advantage of this feature..."
(Something else?)

Thanks,
Steve
0

Technical Writing

259

Solutions

242

Contributors

Technical writing is any written form of writing or drafting technical communication used in a variety of technical and occupational fields, such as computer hardware and software, engineering, chemistry, aeronautics, robotics, finance, consumer electronics, and biotechnology. IT encompasses the largest sub-field within technical communication. The Society for Technical Communication defines technical communication as any form of communication that exhibits one or more of the following characteristics: "(1) communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations; (2) communicating through technology, such as web pages, help files, or social media sites; or (3) providing instructions about how to do something, regardless of the task's technical nature".

Top Experts In
Technical Writing