Still celebrating National IT Professionals Day with 3 months of free Premium Membership. Use Code ITDAY17

x

Technical Writing

264

Solutions

246

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,

To me, a drop-down menu is a list of choices/actions e.g.
- All Accounts
- Internal Accounts
- External Accounts

or

- Patients
- Doctors
- Drugs

However, I sometimes need to document the case where you type in a partial key and then choose from a list of matches. e.g
I type "apple" and see
- Applesauce
- Apple pie
- Apple (red delicious)

To me, the above is not a menu, but a list. Accordingly, would it be kosher to refer to the above as a "drop-down list"?

Thanks,
Steve
0
Free Tool: SSL Checker
LVL 10
Free Tool: SSL Checker

Scans your site and returns information about your SSL implementation and certificate. Helpful for debugging and validating your SSL configuration.

One of a set of tools we are providing to everyone as a way of saying thank you for being a part of the community.

I need to know how to wire internal wiring
0
Hi,

In the fictitious  screenshot below, (which contains only two fields, but my live screenshot for customers has six), and each option is more complex than my example.
Boxed Field Names
I enclosed the field names in black boxes to make them stand out. Accordingly, I wrote:
"This option consists of six settings, boxed in the above screenshot."

But, is "boxed" the correct word here?

Thanks,
Steve
0
SnagIt 13.1.1 (32  bit)/Win10:

In a screenshot, the empty space on the right of a screenshot has this checkered pattern. (Please see example below.) I recall an option that allows me to change to all white, but can't find it.

(In this example, I've scrubbed the content to the left of the border.)
SnagIt Checkered Background
Accordingly.
1. How do I change to all-white?
2. How can I set the default to all-white so I don't have to change it every time?

Thanks,
Steve
0
Quick, for those of you that care about copywriting, typography, and such: what's your favorite way to make an em-dash (—)? My current method is to do a Google search and copy/paste, but this seems terrible and I feel bad every time I do it because I know there are more efficient ways. I've been too lazy busy to train myself to do something better, but maybe learning your favorite way(s) will finally prompt me to take a more efficient approach...

Note: most of my writing is done in a web browser and I tend to bounce between Chrome on a PC and Safari on a Mac.
1
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
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
On Demand Webinar: Networking for the Cloud Era
LVL 10
On Demand Webinar: Networking for the Cloud Era

Did you know SD-WANs can improve network connectivity? Check out this webinar to learn how an SD-WAN simplified, one-click tool can help you migrate and manage data in the cloud.

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
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
Concerto Cloud for Software Providers & ISVs
LVL 4
Concerto Cloud for Software Providers & ISVs

Can Concerto Cloud Services help you focus on evolving your application offerings, while delivering the best cloud experience to your customers? From DevOps to revenue models and customer support, the answer is yes!

Learn how Concerto can help you.

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
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

Technical Writing

264

Solutions

246

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
<
Monthly
>