Improve company productivity with a Business Account.Sign Up

x

Technical Writing

295

Solutions

266

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

In a web application, I have a screen that includes the following (redacted):
What is this icon?
The functionality is that if the thingy to the right of "Confirm" is not present, you can click Confirm to approve a transaction. If the thingy is present, there's an issue with the transaction and you can't approve it at this time.

But, what do I call it? Magnifying glass icon? Or is icon even the correct word.

Oh, the hairs I split... :)

Thanks,
Steve
0
Free Tool: SSL Checker
LVL 12
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.

Hello,

Since I'm not familiar with the MAC, (in fact, I don't have access to one) I have not encountered this syntax before.

In a set of Release Notes, I need to document a feature involving the MAC key combination COMMAND and Click.  Two questions:

1. What's the preferred syntax here?

<Command>-<Click>
<Cmd>-<Click>
Something else?

2. What's the correct verb? Press? Perform? Do? e.g.
Press <Command>-<Click>


Thanks,
Steve
0
Hey everyone,

In the web app I'm documenting we have a number of text fields where, when you start typing something, it displays a list of matches. e.g. if it were a "state" field you might have

New

   New Jersey
  New Mexico
  New York

You can then click the state you wish to select.

Am I correct in saying that the above is not a search box? (The database field is text.)
0
Hello,

To indicate an optional plural, I would write:

Select the checkbox(es) next to the item(s)

But, how about for a word such as "category".

Do I write:

Select the checkbox(es) next to the category(s)

(or)
Select the checkbox(es) next to the categor(ies)

While I suppose this sentence could be rewritten, all I"m looking for is the specific issue of (s) vs (ies).

Thank(s) :)
0
I'm documenting a screen in a web app that has a field that can store a temporal value. It can be in days, weeks, months, years depending on the setting of an adjacent drop-down menu.

e.g. (redacted):

Length of Contract:  ______   <days, weeks, months, years>

My question:

1. What would be a general term for the value placed in the blank field above. I considered Quantity and Amount, but I don't think these terms apply to temporal values.

2. And, while on the subject, how about for <days, weeks, months, years>. Maybe Time Period?

Thanks,
Steve
0
I had this question after viewing I need a synonym for the word "field" (Database context).

I'm documenting a web application screen that contains numerous fields per this redacted example for running (race) data for an athlete.

Date: 02/09/18
Race Name: Experts Exchange Challenge
Distance: 5 miles

Result:   Time: 39:09   PacePerMile: 7:50

Date, Race Name, and Distance are fields.

But how about Result and its elements (Time and PacePerMile)?  I'm calling Result a "field" and it elements "subfields".  Am I on safe ground? (My audience is technical people such as UX designers.)

Thanks!
0
I need a synonym for "field"  as in the database usage of the word (e.g. the first name field, last name field, address field, etc.)
0
Hi,

Suppose (redacted example) I have an application to measure running statistics.

First field (UNITS) is a drop-down menu with the choices (MILES, KILOMETERS, OTHER)
The subsequent fields are determined by the first field.
If UNITS = MILES,:
    One field (Mi.) displays, with numeric input.
If UNITS = KILOMETERS
    One field (Km.) displays, with numeric input.
If UNITS = OTHER
    Two fields display:
        CUSTOM UNIT (text field to enter whatever you want (e.g. meters, furlongs, etc.)
        DISTANCE (where you enter a numeric value e.g. 3 for 3 furlongs).

Is it correct to say that there's a field dependency between the subsequent fields and UNITS? I've heard of that term used if a field's available values depend on some other field

http://www.salesforcetutorial.com/field-dependency-in-salesforce/

but how about in this case? (I'm not using Salesforce, my friend Google found it. :) )

Thanks,
Steve
0
Hi,

I'm documenting a set of (e.g.) ten screens. Nothing fancy, just a bunch of screenshots. Plus, tables containing:
  • Field Name
  • Datatype.

For three of the tables, I need to provide additional info, so I added a Remarks column. But, it's not needed for the remaining seven tables.

Is it considered better form to include the Remarks column anyhow, for consistency's sake? Or, does a column with no info look bad?

Thanks.
0
Hi,
I'm documenting a screen in a web application that contains multiple fields. I need to specify the "type" for each one (e.g. text). What would you call a field where you can check one or more checkboxes? Selection List?
What do you call this list?
Thanks!
Steve
0
Keep up with what's happening at Experts Exchange!
LVL 12
Keep up with what's happening at Experts Exchange!

Sign up to receive Decoded, a new monthly digest with product updates, feature release info, continuing education opportunities, and more.

Hi,

In a web app, I've encountered an icon that looks like that below. Is it called a balloon? Something else?
Balloon Icon?
Thanks.
0
Hey, everyone.

Maybe the falafel I tried to cook tonight is addling my brain :), but I'm drawing a blank here.

I'm documenting a feature that consists of three screens. But, I want to say it the opposite way. That is.

These screens ___________ a single, seamless interface, that allows you to declutter your widgets efficiently. (Obviously redacted. :) )

I'm looking to fill in the blank. I tried "constitute", but it doesn't feel right.....

Any suggestions?
Thanks,
Steve
0
Hey Everyone,

Maybe I'm jumping at shadows after a busy week so far... :)

I encountered the following in something I'm reviewing (redacted)
"This field displays the overall average for all vendors."

But isn't "average" by definition, imply "overall"? I'm thinking I should remove "overall".

Thanks,
Steve
0
Hi,

I've encountered the below icon when documenting a web application. In Chrome (and in my app) it seems to be used to access various applications.

What is the icon?
For documentation purposes, does it have a formal name other than (e.g.) "Applications Icon" that most/all readers would understand? (My audience has decent technical knowledge.)

Thanks.
0
Win10:

Happy Holidays!

Silly question:

What's the term for the Windows button I've highlighted below?

Is this button called RESTORE?
There's Maximize:

(Maximize button)

minimize, close, and this doo-hickey. I've seen it referred to as "restore" on the drop-down menu at the upper-left of the screen. But, is it correct to say,

"When you restore a window to its default size, the data displays yada yada yada..."

Thanks!
0
Hey everyone,

Trying to figure out if something I wrote would be clear to someone familiar with data concepts such as fields, columns, rows, etc.

In this scrubbed example, the data consists of Widgets, each of which belong to a Widget Group.  One of the columns is "Type" (e.g. Utensil, Appliance, etc.)  A report exists that has one row per group, with its widgets below it, if you choose to expand the row with the group. Some report columns (e.g. Type, Manufacturer, etc.) apply to both groups and widgets.

I describe the Type column as follows:
"For widget groups: various if Types differ. Otherwise, the uniform Type displays.

How would you interpret the meaning of "The uniform type displays"?  I want to be sure the reader will understand my intent. :)

Thanks.
0
Hi,

From what I know, if you are documenting a data structure (e.g. JSON) with embedded objects, you might have something like this for the data schema tables:

DISCLAIMER: In the real world, I doubt you'd have a full (e.g.) doctor object embedded in the prescription object. More likely, you'd have a record number for patient, doctor, drug, but the below is useful for this example. :)

PRESCRIPTION OBJECT
Date
Time
Rx Number
Patient Object
Doctor Object
Drug Object
Directions
etc.


You'd then have tables for the aforementioned objects, which themselves could contain objects:
DOCTOR OBJECT
LastName
FirstName
IdNumbers Object
Address
etc.

And in turn...
ID NUMBERS OBJECT
Licence
DEA
NPI
-----------
Now, to the question. I'm documenting an API where some of the embedded objects contain only one field/object. To use the above example, something like:

PRESCRIPTION OBJECT (as before: contains many fields/objects)

DOCTOR OBJECT (Contains one object)
IdNumbers Object

ID NUMBERS OBJECT (Contains one field)
License

Per the above, would I be overdoing it to have separate data tables for these objects containing only one field/object? If so, I'd need to find a clean way to embed everything in the parent table.

Thanks!
Steve
0
Hi,

When we add a new feature to our web application, I insert a "NEW FEATURE" banner into the appropriate page. e.g.

NEW FEATURE: The system now supports reciting pi out to 20 decimal places. Click here for details.

I'm now documenting a change to existing functionality and want to announce this update in a similar manner. But, it's not a new feature. What would be a viable alternate term? ENHANCEMENT? SOFTWARE CHANGE? <Something else?>

Thanks,
Steve
0
What are the rules/guidelines regarding the use of "You",  "I" and other pronouns in writing user manuals and other documentation.
Are there any specific rules for tutorial scripts which will be used by on-screen narrators/talent or tutorial voice over talent?
0
Free Tool: Site Down Detector
LVL 12
Free Tool: Site Down Detector

Helpful to verify reports of your own downtime, or to double check a downed website you are trying to access.

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.

Hi,

Of the two options below, which is preferable?

  1. Page-level settings
  2. Page level settings.

I'm leaning toward #1 but could be convinced otherwise. :)

Thanks,
Steve
0
Hi,

I'm blanking out here on proper terminology. Suppose I have an array (e.g. of seasonal records for a sports team).

2016: Wins: 8. Losses; 2.  Percentage: 80.00
2017: Wins: 4: Losses: 6.  Percentage: 40.00

The dataset also contains a totals object:
Wins:  12: Losses: 8. Percentage: 60.00

Wins &  Losses are the SUM of the individual elements. But, what's the term for the Percentage (60.00). Aggregate?

Need the above for an API guide.
Thanks,
Steve
0
Hi,
I'm writing an API guide for an application that accepts input - and generates output - in JSON format.

Suppose I have the following (redacted) code:
{
   SSN :  "012-34-5678",
   DOB: "1986-10-27",
   Age: 30,
   name: {
      first: "Daffy",
      last : "Duck"
    },
   Department: "Sales"
}

Open in new window


1. Is this entire entity referred to as a block or object?
2. Same for the name element, which contains first/last name.

Also, is JSON syntax considered closer to Java? Or to JavaScript?  The reason I need to know the latter is that I'm showing code samples in Confluence. While Confluence has a Code Block Macro, it does not come with prepackaged JSON formatting.

Thanks,
Steve
0
Hi,

The question below was generated by needing to document a JSON structure, but I suppose it could apply to other data formats as well.

Suppose I have a structure:
{
   name: "John Doe",
   address: "1234 Main Street",
   vitals: {
       hair_color: "brown",
       eyes: "blue",
    },
   DOB: "01-01-2000",
   sex: "Male"  
}

Normally, I'd create a table with one row per data element. But, then I have the vitals block, which contains two data elements. Should I create a separate table for vitals, even though it contains only two fields? And reference it in the main table?

Thanks,
Steve
0
Hi,

After I finish editing an image, I would like to close the file so it's no longer in the editor the next time I invoke it. However, the FILE menu does not contain a CLOSE choice. How, then can I accomplish what I need?

Thanks.
0
Hi,

What is the correct/accepted terminology for a small portion of a screen that does not necessarily contain a data field?
Here's an example from a public website (not from my client work).

1. Click 'Races'.
2. You will see the following: ___________________.  (segment? display? snippet?)
 Example3. To filter by distance...
etc.

How would you fill in the blank in step 2?
Thanks.
0

Technical Writing

295

Solutions

266

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
>