Plain language with long required phrases
I am trying to create documentation for an application, and it's for end users who use keyboard (not mouse) and a screen reader.
Some of our conventions require us to always use the full phrase as listed on screen: if we're talking about the category combo box, but the label says "Please pick a Category:" [sic], that's what we have to use.
Another convention is for keyboard shortcuts -- they are always several "words" long, as we use white space (or I go non-breaking-space) between each element of it. So we have CTRL + INSERT + T for tables list.
So as you may have noticed, I have a tendency towards long sentences with many clauses. I'm using Hemingway to check each section for Plain Language, and I'm trying to revise the hard/very hard sentences.
The problem is, my sentences are often very long and it's not my fault!
If I replace a multi-word phrase whether keyboard shortcut or on-screen label with "xx," that usually brings the sentence's word count down that the sentences "pass."
Is this "cheating?" Are these "terms of art" and it's ok to say "Ctrl + INSert + number pad 6" is understood as a "word?"
Should only the keyboard shortcuts count as 1-word, as the users may know them from other uses of the screenreader, (so replacing them mentally with "X" for a plainLang check is ok), but "envelope Send Email checkbox" still has to count as 4 words, as they would be new to the user? Or only the first-usage within a section?
Note: My workplace doesn't allow the use of 2nd person, despite PlainLang encouraging personal pronouns -- I'm already "wasting" words by having to always say "the user" instead of "you."
I'd like to know if other technical writers have a consensus on how to handle these conflicts.
style technical-writing non-fiction
asked Apr 4 at 14:07
AprilApril
2,328636
|
show 4 more comments
I am trying to create documentation for an application, and it's for end users who use keyboard (not mouse) and a screen reader.
Some of our conventions require us to always use the full phrase as listed on screen: if we're talking about the category combo box, but the label says "Please pick a Category:" [sic], that's what we have to use.
Another convention is for keyboard shortcuts -- they are always several "words" long, as we use white space (or I go non-breaking-space) between each element of it. So we have CTRL + INSERT + T for tables list.
So as you may have noticed, I have a tendency towards long sentences with many clauses. I'm using Hemingway to check each section for Plain Language, and I'm trying to revise the hard/very hard sentences.
The problem is, my sentences are often very long and it's not my fault!
If I replace a multi-word phrase whether keyboard shortcut or on-screen label with "xx," that usually brings the sentence's word count down that the sentences "pass."
Is this "cheating?" Are these "terms of art" and it's ok to say "Ctrl + INSert + number pad 6" is understood as a "word?"
Should only the keyboard shortcuts count as 1-word, as the users may know them from other uses of the screenreader, (so replacing them mentally with "X" for a plainLang check is ok), but "envelope Send Email checkbox" still has to count as 4 words, as they would be new to the user? Or only the first-usage within a section?
Note: My workplace doesn't allow the use of 2nd person, despite PlainLang encouraging personal pronouns -- I'm already "wasting" words by having to always say "the user" instead of "you."
I'd like to know if other technical writers have a consensus on how to handle these conflicts.
style technical-writing non-fiction
asked Apr 4 at 14:07
AprilApril
2,328636
Lot's of questions here… Is it possible to use inferred 2nd person, where "you/the user" is just skipped?
– wetcircuit
Apr 4 at 14:12
Yes, I do use a lot of that. "Press insert+f5, navigate with down arrows to the most accurate option, then press enter to activate it."
– April
Apr 4 at 14:42
yeesh, that is a long sentence… And this is necessary every time?
– wetcircuit
Apr 4 at 15:18
You might try tricking the software by replacing the spaces in those phrases with some special character you don't normally use; like '^', which you can do a global replace on later with a space (or non-breaking space). So "CTRL^+^INSERT^+^T", and maybe Hemingway will count it as a single word.
– Amadeus
Apr 4 at 15:39
1
I wonder if there are conventions specific to screen-readers that should factor into this. This question would benefit from input from somebody who regularly uses a screen-reader.
– Monica Cellio♦
Apr 4 at 15:39
|
show 4 more comments
I am trying to create documentation for an application, and it's for end users who use keyboard (not mouse) and a screen reader.
Some of our conventions require us to always use the full phrase as listed on screen: if we're talking about the category combo box, but the label says "Please pick a Category:" [sic], that's what we have to use.
Another convention is for keyboard shortcuts -- they are always several "words" long, as we use white space (or I go non-breaking-space) between each element of it. So we have CTRL + INSERT + T for tables list.
So as you may have noticed, I have a tendency towards long sentences with many clauses. I'm using Hemingway to check each section for Plain Language, and I'm trying to revise the hard/very hard sentences.
The problem is, my sentences are often very long and it's not my fault!
If I replace a multi-word phrase whether keyboard shortcut or on-screen label with "xx," that usually brings the sentence's word count down that the sentences "pass."
Is this "cheating?" Are these "terms of art" and it's ok to say "Ctrl + INSert + number pad 6" is understood as a "word?"
Should only the keyboard shortcuts count as 1-word, as the users may know them from other uses of the screenreader, (so replacing them mentally with "X" for a plainLang check is ok), but "envelope Send Email checkbox" still has to count as 4 words, as they would be new to the user? Or only the first-usage within a section?
Note: My workplace doesn't allow the use of 2nd person, despite PlainLang encouraging personal pronouns -- I'm already "wasting" words by having to always say "the user" instead of "you."
I'd like to know if other technical writers have a consensus on how to handle these conflicts.
style technical-writing non-fiction
asked Apr 4 at 14:07
AprilApril
2,328636
I am trying to create documentation for an application, and it's for end users who use keyboard (not mouse) and a screen reader.
Some of our conventions require us to always use the full phrase as listed on screen: if we're talking about the category combo box, but the label says "Please pick a Category:" [sic], that's what we have to use.
Another convention is for keyboard shortcuts -- they are always several "words" long, as we use white space (or I go non-breaking-space) between each element of it. So we have CTRL + INSERT + T for tables list.
So as you may have noticed, I have a tendency towards long sentences with many clauses. I'm using Hemingway to check each section for Plain Language, and I'm trying to revise the hard/very hard sentences.
The problem is, my sentences are often very long and it's not my fault!
If I replace a multi-word phrase whether keyboard shortcut or on-screen label with "xx," that usually brings the sentence's word count down that the sentences "pass."
Is this "cheating?" Are these "terms of art" and it's ok to say "Ctrl + INSert + number pad 6" is understood as a "word?"
Should only the keyboard shortcuts count as 1-word, as the users may know them from other uses of the screenreader, (so replacing them mentally with "X" for a plainLang check is ok), but "envelope Send Email checkbox" still has to count as 4 words, as they would be new to the user? Or only the first-usage within a section?
Note: My workplace doesn't allow the use of 2nd person, despite PlainLang encouraging personal pronouns -- I'm already "wasting" words by having to always say "the user" instead of "you."
I'd like to know if other technical writers have a consensus on how to handle these conflicts.
style technical-writing non-fiction
style technical-writing non-fiction
asked Apr 4 at 14:07
AprilApril
2,328636
asked Apr 4 at 14:07
AprilApril
2,328636
asked Apr 4 at 14:07
AprilApril
2,328636
asked Apr 4 at 14:07
AprilApril
2,328636
asked Apr 4 at 14:07
AprilApril
2,328636
2,328636
Lot's of questions here… Is it possible to use inferred 2nd person, where "you/the user" is just skipped?
– wetcircuit
Apr 4 at 14:12
Yes, I do use a lot of that. "Press insert+f5, navigate with down arrows to the most accurate option, then press enter to activate it."
– April
Apr 4 at 14:42
yeesh, that is a long sentence… And this is necessary every time?
– wetcircuit
Apr 4 at 15:18
You might try tricking the software by replacing the spaces in those phrases with some special character you don't normally use; like '^', which you can do a global replace on later with a space (or non-breaking space). So "CTRL^+^INSERT^+^T", and maybe Hemingway will count it as a single word.
– Amadeus
Apr 4 at 15:39
1
I wonder if there are conventions specific to screen-readers that should factor into this. This question would benefit from input from somebody who regularly uses a screen-reader.
– Monica Cellio♦
Apr 4 at 15:39
|
show 4 more comments
Lot's of questions here… Is it possible to use inferred 2nd person, where "you/the user" is just skipped?
– wetcircuit
Apr 4 at 14:12
Yes, I do use a lot of that. "Press insert+f5, navigate with down arrows to the most accurate option, then press enter to activate it."
– April
Apr 4 at 14:42
yeesh, that is a long sentence… And this is necessary every time?
– wetcircuit
Apr 4 at 15:18
You might try tricking the software by replacing the spaces in those phrases with some special character you don't normally use; like '^', which you can do a global replace on later with a space (or non-breaking space). So "CTRL^+^INSERT^+^T", and maybe Hemingway will count it as a single word.
– Amadeus
Apr 4 at 15:39
1
I wonder if there are conventions specific to screen-readers that should factor into this. This question would benefit from input from somebody who regularly uses a screen-reader.
– Monica Cellio♦
Apr 4 at 15:39
Lot's of questions here… Is it possible to use inferred 2nd person, where "you/the user" is just skipped?
– wetcircuit
Apr 4 at 14:12
Lot's of questions here… Is it possible to use inferred 2nd person, where "you/the user" is just skipped?
– wetcircuit
Apr 4 at 14:12
Yes, I do use a lot of that. "Press insert+f5, navigate with down arrows to the most accurate option, then press enter to activate it."
– April
Apr 4 at 14:42
Yes, I do use a lot of that. "Press insert+f5, navigate with down arrows to the most accurate option, then press enter to activate it."
– April
Apr 4 at 14:42
yeesh, that is a long sentence… And this is necessary every time?
– wetcircuit
Apr 4 at 15:18
yeesh, that is a long sentence… And this is necessary every time?
– wetcircuit
Apr 4 at 15:18
You might try tricking the software by replacing the spaces in those phrases with some special character you don't normally use; like '^', which you can do a global replace on later with a space (or non-breaking space). So "CTRL^+^INSERT^+^T", and maybe Hemingway will count it as a single word.
– Amadeus
Apr 4 at 15:39
You might try tricking the software by replacing the spaces in those phrases with some special character you don't normally use; like '^', which you can do a global replace on later with a space (or non-breaking space). So "CTRL^+^INSERT^+^T", and maybe Hemingway will count it as a single word.
– Amadeus
Apr 4 at 15:39
1
1
I wonder if there are conventions specific to screen-readers that should factor into this. This question would benefit from input from somebody who regularly uses a screen-reader.
– Monica Cellio♦
Apr 4 at 15:39
I wonder if there are conventions specific to screen-readers that should factor into this. This question would benefit from input from somebody who regularly uses a screen-reader.
– Monica Cellio♦
Apr 4 at 15:39
|
show 4 more comments
1 Answer
1
active
oldest
votes
It's possible you're tying yourself in knots with Hemingway which is, perhaps, better for prose writers than technical writers.
Hemingway themselves state:
But what if I want to break the rules?
Rules are meant to be broken. If you know what you're doing, don't let
us stop you. View our suggestions as just that.
I used to write instructional manuals for IBM and Sun Microsystems. For new users, I'd try to emulate the formatting of a Dummies book. Word 2007 for Dummies has a Look Inside for you to see how they handle it.
If you aren't constrained by company formatting, try splitting out the processes with a quick explanation, followed by a numbered list of commands, with the clicks and keyboard strokes in bold, and explanations unbolded. Like this:
IMPORTING A PICTURE INTO A MS WORD DOCUMENT
Importing pictures into Word is very easy, just take the following steps:
Left click the INSERT menu option. A pop up menu appears.
From the pop up menu, select PICTURES. A side menu appears.
From the side menu, select PICTURE FROM FILE.
Stripping each method into numbered lists avoids long, complex sentences with commands embedded in the middle. Of short sentences like this, Hemingway should approve.
I've used mouse clicks in this example, which you would just switch out for keyboard commands. I didn't know the keyboard commands for this example!
HTH, but difficult to advise better when I don't know all the rules you have to abide by.
answered Apr 4 at 17:06
GGxGGx
6,82811343
No pictures -- these users are visually impaired. Things are already numbered and as short as I can make them.
– April
Apr 4 at 19:17
1
Then is it possible you've already done a great job and Hemingway is making you doubt your own skills?
– GGx
Apr 4 at 19:19
1
It may be. I haven't done a tech document before (though I've taught tech writing), and I've never had so much time to proofread/edit the heck out of something. As an instructor, it was write&go (assignment sheets) , or give a few tips in student feedback. We don't have much collaboration in this office, which is partly what I was hoping for.
– April
Apr 4 at 19:24
@April is there really no-one in your office who could check your work and make sure you are heading in the right direction? If you have already formatted it in this way, as simple as a Dummies book, while following the company guidelines, I would say you have done your job. The only way to know for sure is to hand it over and get feedback. But it does sound to me like you may be overthinking and overanalysing it with tools like Hemingway. It's just a tool to help you, not to be followed blindly. Perhaps drop a comment on here and let us know if they were happy with it! Good luck.
– GGx
Apr 5 at 12:51
I did a read-aloud edit, so I found some errors (some formatting, some were misphrasings), but later today I'll declare it "done." I've met with one co-writer a little, but she has her own projects. She told me that first draft wasn't what I'd call a first draft, but it should be "as complete/correct as possible." (Partially I asked this question due to the tag-of-the-week question drive, not pure anxiety)
– April
Apr 5 at 13:10
add a comment |
Your Answer
StackExchange.ready(function() {
var channelOptions = {
tags: "".split(" "),
id: "166"
};
initTagRenderer("".split(" "), "".split(" "), channelOptions);
StackExchange.using("externalEditor", function() {
// Have to fire editor after snippets, if snippets enabled
if (StackExchange.settings.snippets.snippetsEnabled) {
StackExchange.using("snippets", function() {
createEditor();
});
}
else {
createEditor();
}
});
function createEditor() {
StackExchange.prepareEditor({
heartbeatType: 'answer',
autoActivateHeartbeat: false,
convertImagesToLinks: false,
noModals: true,
showLowRepImageUploadWarning: true,
reputationToPostImages: null,
bindNavPrevention: true,
postfix: "",
imageUploader: {
brandingHtml: "Powered by u003ca class="icon-imgur-white" href="https://imgur.com/"u003eu003c/au003e",
contentPolicyHtml: "User contributions licensed under u003ca href="https://creativecommons.org/licenses/by-sa/3.0/"u003ecc by-sa 3.0 with attribution requiredu003c/au003e u003ca href="https://stackoverflow.com/legal/content-policy"u003e(content policy)u003c/au003e",
allowUrls: true
},
noCode: true, onDemand: true,
discardSelector: ".discard-answer"
,immediatelyShowMarkdownHelp:true
});
}
});
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fwriting.stackexchange.com%2fquestions%2f44362%2fplain-language-with-long-required-phrases%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
1 Answer
1
active
oldest
votes
1 Answer
1
active
oldest
votes
active
oldest
votes
active
oldest
votes
It's possible you're tying yourself in knots with Hemingway which is, perhaps, better for prose writers than technical writers.
Hemingway themselves state:
But what if I want to break the rules?
Rules are meant to be broken. If you know what you're doing, don't let
us stop you. View our suggestions as just that.
I used to write instructional manuals for IBM and Sun Microsystems. For new users, I'd try to emulate the formatting of a Dummies book. Word 2007 for Dummies has a Look Inside for you to see how they handle it.
If you aren't constrained by company formatting, try splitting out the processes with a quick explanation, followed by a numbered list of commands, with the clicks and keyboard strokes in bold, and explanations unbolded. Like this:
IMPORTING A PICTURE INTO A MS WORD DOCUMENT
Importing pictures into Word is very easy, just take the following steps:
Left click the INSERT menu option. A pop up menu appears.
From the pop up menu, select PICTURES. A side menu appears.
From the side menu, select PICTURE FROM FILE.
Stripping each method into numbered lists avoids long, complex sentences with commands embedded in the middle. Of short sentences like this, Hemingway should approve.
I've used mouse clicks in this example, which you would just switch out for keyboard commands. I didn't know the keyboard commands for this example!
HTH, but difficult to advise better when I don't know all the rules you have to abide by.
answered Apr 4 at 17:06
GGxGGx
6,82811343
No pictures -- these users are visually impaired. Things are already numbered and as short as I can make them.
– April
Apr 4 at 19:17
1
Then is it possible you've already done a great job and Hemingway is making you doubt your own skills?
– GGx
Apr 4 at 19:19
1
It may be. I haven't done a tech document before (though I've taught tech writing), and I've never had so much time to proofread/edit the heck out of something. As an instructor, it was write&go (assignment sheets) , or give a few tips in student feedback. We don't have much collaboration in this office, which is partly what I was hoping for.
– April
Apr 4 at 19:24
@April is there really no-one in your office who could check your work and make sure you are heading in the right direction? If you have already formatted it in this way, as simple as a Dummies book, while following the company guidelines, I would say you have done your job. The only way to know for sure is to hand it over and get feedback. But it does sound to me like you may be overthinking and overanalysing it with tools like Hemingway. It's just a tool to help you, not to be followed blindly. Perhaps drop a comment on here and let us know if they were happy with it! Good luck.
– GGx
Apr 5 at 12:51
I did a read-aloud edit, so I found some errors (some formatting, some were misphrasings), but later today I'll declare it "done." I've met with one co-writer a little, but she has her own projects. She told me that first draft wasn't what I'd call a first draft, but it should be "as complete/correct as possible." (Partially I asked this question due to the tag-of-the-week question drive, not pure anxiety)
– April
Apr 5 at 13:10
add a comment |
It's possible you're tying yourself in knots with Hemingway which is, perhaps, better for prose writers than technical writers.
Hemingway themselves state:
But what if I want to break the rules?
Rules are meant to be broken. If you know what you're doing, don't let
us stop you. View our suggestions as just that.
I used to write instructional manuals for IBM and Sun Microsystems. For new users, I'd try to emulate the formatting of a Dummies book. Word 2007 for Dummies has a Look Inside for you to see how they handle it.
If you aren't constrained by company formatting, try splitting out the processes with a quick explanation, followed by a numbered list of commands, with the clicks and keyboard strokes in bold, and explanations unbolded. Like this:
IMPORTING A PICTURE INTO A MS WORD DOCUMENT
Importing pictures into Word is very easy, just take the following steps:
Left click the INSERT menu option. A pop up menu appears.
From the pop up menu, select PICTURES. A side menu appears.
From the side menu, select PICTURE FROM FILE.
Stripping each method into numbered lists avoids long, complex sentences with commands embedded in the middle. Of short sentences like this, Hemingway should approve.
I've used mouse clicks in this example, which you would just switch out for keyboard commands. I didn't know the keyboard commands for this example!
HTH, but difficult to advise better when I don't know all the rules you have to abide by.
answered Apr 4 at 17:06
GGxGGx
6,82811343
No pictures -- these users are visually impaired. Things are already numbered and as short as I can make them.
– April
Apr 4 at 19:17
1
Then is it possible you've already done a great job and Hemingway is making you doubt your own skills?
– GGx
Apr 4 at 19:19
1
It may be. I haven't done a tech document before (though I've taught tech writing), and I've never had so much time to proofread/edit the heck out of something. As an instructor, it was write&go (assignment sheets) , or give a few tips in student feedback. We don't have much collaboration in this office, which is partly what I was hoping for.
– April
Apr 4 at 19:24
@April is there really no-one in your office who could check your work and make sure you are heading in the right direction? If you have already formatted it in this way, as simple as a Dummies book, while following the company guidelines, I would say you have done your job. The only way to know for sure is to hand it over and get feedback. But it does sound to me like you may be overthinking and overanalysing it with tools like Hemingway. It's just a tool to help you, not to be followed blindly. Perhaps drop a comment on here and let us know if they were happy with it! Good luck.
– GGx
Apr 5 at 12:51
I did a read-aloud edit, so I found some errors (some formatting, some were misphrasings), but later today I'll declare it "done." I've met with one co-writer a little, but she has her own projects. She told me that first draft wasn't what I'd call a first draft, but it should be "as complete/correct as possible." (Partially I asked this question due to the tag-of-the-week question drive, not pure anxiety)
– April
Apr 5 at 13:10
add a comment |
It's possible you're tying yourself in knots with Hemingway which is, perhaps, better for prose writers than technical writers.
Hemingway themselves state:
But what if I want to break the rules?
Rules are meant to be broken. If you know what you're doing, don't let
us stop you. View our suggestions as just that.
I used to write instructional manuals for IBM and Sun Microsystems. For new users, I'd try to emulate the formatting of a Dummies book. Word 2007 for Dummies has a Look Inside for you to see how they handle it.
If you aren't constrained by company formatting, try splitting out the processes with a quick explanation, followed by a numbered list of commands, with the clicks and keyboard strokes in bold, and explanations unbolded. Like this:
IMPORTING A PICTURE INTO A MS WORD DOCUMENT
Importing pictures into Word is very easy, just take the following steps:
Left click the INSERT menu option. A pop up menu appears.
From the pop up menu, select PICTURES. A side menu appears.
From the side menu, select PICTURE FROM FILE.
Stripping each method into numbered lists avoids long, complex sentences with commands embedded in the middle. Of short sentences like this, Hemingway should approve.
I've used mouse clicks in this example, which you would just switch out for keyboard commands. I didn't know the keyboard commands for this example!
HTH, but difficult to advise better when I don't know all the rules you have to abide by.
answered Apr 4 at 17:06
GGxGGx
6,82811343
It's possible you're tying yourself in knots with Hemingway which is, perhaps, better for prose writers than technical writers.
Hemingway themselves state:
But what if I want to break the rules?
Rules are meant to be broken. If you know what you're doing, don't let
us stop you. View our suggestions as just that.
I used to write instructional manuals for IBM and Sun Microsystems. For new users, I'd try to emulate the formatting of a Dummies book. Word 2007 for Dummies has a Look Inside for you to see how they handle it.
If you aren't constrained by company formatting, try splitting out the processes with a quick explanation, followed by a numbered list of commands, with the clicks and keyboard strokes in bold, and explanations unbolded. Like this:
IMPORTING A PICTURE INTO A MS WORD DOCUMENT
Importing pictures into Word is very easy, just take the following steps:
Left click the INSERT menu option. A pop up menu appears.
From the pop up menu, select PICTURES. A side menu appears.
From the side menu, select PICTURE FROM FILE.
Stripping each method into numbered lists avoids long, complex sentences with commands embedded in the middle. Of short sentences like this, Hemingway should approve.
I've used mouse clicks in this example, which you would just switch out for keyboard commands. I didn't know the keyboard commands for this example!
HTH, but difficult to advise better when I don't know all the rules you have to abide by.
answered Apr 4 at 17:06
GGxGGx
6,82811343
answered Apr 4 at 17:06
GGxGGx
6,82811343
answered Apr 4 at 17:06
GGxGGx
6,82811343
answered Apr 4 at 17:06
GGxGGx
6,82811343
6,82811343
No pictures -- these users are visually impaired. Things are already numbered and as short as I can make them.
– April
Apr 4 at 19:17
1
Then is it possible you've already done a great job and Hemingway is making you doubt your own skills?
– GGx
Apr 4 at 19:19
1
It may be. I haven't done a tech document before (though I've taught tech writing), and I've never had so much time to proofread/edit the heck out of something. As an instructor, it was write&go (assignment sheets) , or give a few tips in student feedback. We don't have much collaboration in this office, which is partly what I was hoping for.
– April
Apr 4 at 19:24
@April is there really no-one in your office who could check your work and make sure you are heading in the right direction? If you have already formatted it in this way, as simple as a Dummies book, while following the company guidelines, I would say you have done your job. The only way to know for sure is to hand it over and get feedback. But it does sound to me like you may be overthinking and overanalysing it with tools like Hemingway. It's just a tool to help you, not to be followed blindly. Perhaps drop a comment on here and let us know if they were happy with it! Good luck.
– GGx
Apr 5 at 12:51
I did a read-aloud edit, so I found some errors (some formatting, some were misphrasings), but later today I'll declare it "done." I've met with one co-writer a little, but she has her own projects. She told me that first draft wasn't what I'd call a first draft, but it should be "as complete/correct as possible." (Partially I asked this question due to the tag-of-the-week question drive, not pure anxiety)
– April
Apr 5 at 13:10
add a comment |
No pictures -- these users are visually impaired. Things are already numbered and as short as I can make them.
– April
Apr 4 at 19:17
1
Then is it possible you've already done a great job and Hemingway is making you doubt your own skills?
– GGx
Apr 4 at 19:19
1
It may be. I haven't done a tech document before (though I've taught tech writing), and I've never had so much time to proofread/edit the heck out of something. As an instructor, it was write&go (assignment sheets) , or give a few tips in student feedback. We don't have much collaboration in this office, which is partly what I was hoping for.
– April
Apr 4 at 19:24
@April is there really no-one in your office who could check your work and make sure you are heading in the right direction? If you have already formatted it in this way, as simple as a Dummies book, while following the company guidelines, I would say you have done your job. The only way to know for sure is to hand it over and get feedback. But it does sound to me like you may be overthinking and overanalysing it with tools like Hemingway. It's just a tool to help you, not to be followed blindly. Perhaps drop a comment on here and let us know if they were happy with it! Good luck.
– GGx
Apr 5 at 12:51
I did a read-aloud edit, so I found some errors (some formatting, some were misphrasings), but later today I'll declare it "done." I've met with one co-writer a little, but she has her own projects. She told me that first draft wasn't what I'd call a first draft, but it should be "as complete/correct as possible." (Partially I asked this question due to the tag-of-the-week question drive, not pure anxiety)
– April
Apr 5 at 13:10
No pictures -- these users are visually impaired. Things are already numbered and as short as I can make them.
– April
Apr 4 at 19:17
No pictures -- these users are visually impaired. Things are already numbered and as short as I can make them.
– April
Apr 4 at 19:17
1
1
Then is it possible you've already done a great job and Hemingway is making you doubt your own skills?
– GGx
Apr 4 at 19:19
Then is it possible you've already done a great job and Hemingway is making you doubt your own skills?
– GGx
Apr 4 at 19:19
1
1
It may be. I haven't done a tech document before (though I've taught tech writing), and I've never had so much time to proofread/edit the heck out of something. As an instructor, it was write&go (assignment sheets) , or give a few tips in student feedback. We don't have much collaboration in this office, which is partly what I was hoping for.
– April
Apr 4 at 19:24
It may be. I haven't done a tech document before (though I've taught tech writing), and I've never had so much time to proofread/edit the heck out of something. As an instructor, it was write&go (assignment sheets) , or give a few tips in student feedback. We don't have much collaboration in this office, which is partly what I was hoping for.
– April
Apr 4 at 19:24
@April is there really no-one in your office who could check your work and make sure you are heading in the right direction? If you have already formatted it in this way, as simple as a Dummies book, while following the company guidelines, I would say you have done your job. The only way to know for sure is to hand it over and get feedback. But it does sound to me like you may be overthinking and overanalysing it with tools like Hemingway. It's just a tool to help you, not to be followed blindly. Perhaps drop a comment on here and let us know if they were happy with it! Good luck.
– GGx
Apr 5 at 12:51
@April is there really no-one in your office who could check your work and make sure you are heading in the right direction? If you have already formatted it in this way, as simple as a Dummies book, while following the company guidelines, I would say you have done your job. The only way to know for sure is to hand it over and get feedback. But it does sound to me like you may be overthinking and overanalysing it with tools like Hemingway. It's just a tool to help you, not to be followed blindly. Perhaps drop a comment on here and let us know if they were happy with it! Good luck.
– GGx
Apr 5 at 12:51
I did a read-aloud edit, so I found some errors (some formatting, some were misphrasings), but later today I'll declare it "done." I've met with one co-writer a little, but she has her own projects. She told me that first draft wasn't what I'd call a first draft, but it should be "as complete/correct as possible." (Partially I asked this question due to the tag-of-the-week question drive, not pure anxiety)
– April
Apr 5 at 13:10
I did a read-aloud edit, so I found some errors (some formatting, some were misphrasings), but later today I'll declare it "done." I've met with one co-writer a little, but she has her own projects. She told me that first draft wasn't what I'd call a first draft, but it should be "as complete/correct as possible." (Partially I asked this question due to the tag-of-the-week question drive, not pure anxiety)
– April
Apr 5 at 13:10
add a comment |
Thanks for contributing an answer to Writing Stack Exchange!
- Please be sure to answer the question. Provide details and share your research!
But avoid …
- Asking for help, clarification, or responding to other answers.
- Making statements based on opinion; back them up with references or personal experience.
To learn more, see our tips on writing great answers.
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
StackExchange.ready(
function () {
StackExchange.openid.initPostLogin('.new-post-login', 'https%3a%2f%2fwriting.stackexchange.com%2fquestions%2f44362%2fplain-language-with-long-required-phrases%23new-answer', 'question_page');
}
);
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Sign up or log in
StackExchange.ready(function () {
StackExchange.helpers.onClickDraftSave('#login-link');
});
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Sign up using Google
Sign up using Facebook
Sign up using Email and Password
Post as a guest
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Required, but never shown
Lot's of questions here… Is it possible to use inferred 2nd person, where "you/the user" is just skipped?
– wetcircuit
Apr 4 at 14:12
Yes, I do use a lot of that. "Press insert+f5, navigate with down arrows to the most accurate option, then press enter to activate it."
– April
Apr 4 at 14:42
yeesh, that is a long sentence… And this is necessary every time?
– wetcircuit
Apr 4 at 15:18
You might try tricking the software by replacing the spaces in those phrases with some special character you don't normally use; like '^', which you can do a global replace on later with a space (or non-breaking space). So "CTRL^+^INSERT^+^T", and maybe Hemingway will count it as a single word.
– Amadeus
Apr 4 at 15:39
1
I wonder if there are conventions specific to screen-readers that should factor into this. This question would benefit from input from somebody who regularly uses a screen-reader.
– Monica Cellio♦
Apr 4 at 15:39