MadCap Software Forums

This is really more of tech writing question than a Flare question, but I'm interested in knowing what other writers think about this issue.
I work with a team that consists of one other (less experienced) writer, two product analysts, and a project manager, none of whom have any tech writing experience. I find myself having to argue against the notion of writing CSH (and other) content that includes images of buttons that are on the dialog, with descriptions of their function, for buttons that are universally used. "Click the Add button to add an item to the list." "Highlight an item, and then click Delete to delete the item."
I do not find that kind of information helpful in the least, but find myself continually out-voted on these issues.
There are, of course, exceptions. Some buttons are a little less self-evident.
If you describe one button, do you necessarily have to describe them all?
How do you apply rules that ensure the content is helpful without dumbing-down your help in these instances?
Do you ever put screen captures in a CSH? (Which, by their nature, assume the user is looking at the interface.) Particularly of buttons?
Another example is a procedure topic that describes how to add, edit, and remove a template.
When you click Add or Edit, both open the Edit template dialog, so other than modifying the steps to say "...to add or edit..." or "...enter or modify..." all the rest of the steps are identical.
Would you create one procedure that includes references to both processes, as above, or create two separate procedures? Or two separate topics?
If you have a section that is titled "To remove a template" and all the user has to do is highlight the item and click Remove, does that require documentation? In its own section? In its own topic? (Note that the user does need to know that clicking Remove, as the label indicates, does not delete the template, but merely removes it from the current list. Our software, unfortunately, has used these labels somewhat interchangeably, but that is changing.) I advocated for no more information than this, but was out-voted. What would you do in this instance?
Am I wrong about this?
Thanks for your input.

Shooting from the hip here...

One of my guiding principles as a tech writer is "Don't document the obvious."

Another is never (or perhaps very rarely) include screenshots in reference topics about windows/screens full of properties to be set. Yes I assume the user is looking at the screen, so the screenshot adds little value, but a lot of maintenance overhead. As soon as a new field is added, or if a field is renamed or resized or moved, the screenshot becomes obsolete. I'd much rather just add the description of the new field or edit/rename/move the description of the existing field. And of course if one needs to localize content, localizing screenshots can be quite expensive.

I could go on, but hubby just called to say he's five minutes away and then it's off to dinner for me.

Hi docudramaqueen

I agree with your approach. The old Einstein quote sums it up:

Albert Einstein wrote:Make everything as simple as possible, but not simpler.

I agree with Nita about screenshot maintenance and localization issues. We are stripping out all screenshots that contain text from our docs, to reduce localisation costs. A lot of our internal reviewers object, but we have a mandate from management, so it is a done deal, no discussion.

That might be an approach that you could use. It sounds like you need a solid style guide to lay down the law. If you make it a core principle that your style guide is definitive and that deviations are not permitted, these issues are instantly resolved (get your style guide recognised by management). So I think your challenge is to come up with a style guide that fits your approach

I realise that your first task is to convince your colleagues that your style is better. You will probably get some validation from this forum, but if you research some style guides from successful tech/comms companies (often available online), you might also find answers there. Then you can go to your colleagues and say "look, see, this is how MegaCorp does it and they have great docs. Let's model our style guide on that."

Good luck!

I'd also advocate only documenting what needs documenting.
Including unnecessary documentation can put the reader off. It's important that the reader can find the information quickly, and actually know that they've found the right information - this is harder if the key thing they're looking for is hidden amongst too much information. Readers will typically 'scan' the text anyway, so removing unnecessary text/images will help people find what they're looking for.

Of course the tricky part is determining what 'needs' documenting, but you can do a bit of research here. You could speak to support staff to find out what areas people actually have problems with. Another way would be to put your help online, and use analytics to see what topics people are actually viewing or searching for. Another way is to conduct user research and observe people using your product, and see how/when they use the help (of course you need time/resources to do this, or a UX team that can do it for you).
If you have a range of products, perhaps you could trial the 'reduced' documentation on one of your smaller products, then monitor the results - i.e. do people contact support more as a result, or does it not make any difference?

At the end of the day, what your customer needs determines what your documentation should be like, so if you can show you've done some research and taken this into account, having this evidence should give a lot more weight/direction when it comes to any future arguments and decisions.

Generally, I never include screenshots unless I'm writing topics that specifically refer to the visual appearance of something; e.g. if I were writing Flare's help, I'd probably include screenshots to show the difference between the standard and ribbon interfaces, or the difference between the normal and responsive skins.
I do include images for things like icons or buttons, but only if the icon/button has no on-screen text (i.e. a visible label, not a tooltip).
If you're documenting a more visual/graphical application (e.g. an image editor, reports/graphing tool), then producing videos might be a more effective way to provide assistance than traditional help topics with static images.

For the add/edit scenario, I'd probably have one topic explaining how to add something. I wouldn't include procedural steps for editing (as these are usually virtually identical), but might need to add some notes about editing if required, e.g. explain why something may be locked from editing. If the topic covers both add/edit, I'd not call it 'Add Widgets', but go for something like 'Widgets' or 'Manage Widgets'.

For the remove template example, I probably would include a section on that - just because you hinted there is ambiguity over what happens when you 'remove' it, so it's likely a user might look for that, and the information needs to reside somewhere.

I would never take screenshots of buttons that have a label. If they're a picture they should have a tooltip so, for example a Browse button that is just three dots, I say "... click the Browse button [pic of button with three dots] to xxx..." or if it has the word "Browse" on it, I say "...click Browse to xxx..."

As I'm single-sourcing, we have screenshots that are included in the PDF, so that someone who's reading it away from the software can see what's what.

If you do get outvoted on "Click the Add button to add an item to a list", make it a snippet, then it only has to be maintained in one place.

As for what to document, the key principle is to know your audience. If you are writing for a techie audience who know how to use Windows, then don't bother describing the Add button. If, on the other hand, you're writing for people whose main role is to do stuff, not to use software, then you might need to "dumb down" your help a bit to cater for the users who are actually more likely to need your help.

I disagree to some extent. Does the Add button need documentation? Of course it does! It does need to be covered because it is usually a very important control for retaining user entries. So in the DITA mindset the Add button gets described in the procedure description (step by step instructions). In the help that I wrote I used styles to identify what a button is with bold font. So rather than writing "Click the Add button to add an item to the list." I wrote it as "Click Add to add an item to the list." Less words and the UI controls involved are prominent. The user would then have to read the heading, the first step, and then change to cursory reading picking up the bold control names.
I don't think it is necessary to add documentation about every Add button showing a picture of the Add button and describing what that button does, especially when there are dozens of Add buttons across the application. Instead, I'd create on reference topic detailing common UI controls, again without showing an image. The reference topics detailing the controls for each page or dialog would then link to that common controls reference topic.
I think the users get the most value out of the task topics. "How do I do this?" is likely the most common question. The second question is "What does this do?" where the reference topics come into play. Lastly, "Why did they do it this way?" is more for concept topics. In all those topics only include images of the UI when it is necessary and difficult to explain in words. Images are incredibly cumbersome to localize and these UI images are typically outdated by the time the user sees them. That said, a clear no to full screen captures, use screen portraits instead (see Andy Robertson's excellent blog post about that). I'd make one exception if error messages are displayed in dialogs. I think in that case it makes it easier to find the description of the error by image. What I did in the past was create a reference topic with ALL error messages in alphabetical order based on message text. Each error message description received a bookmark and each task topic had then links to the applicable error messages that might occur during that process.

I also disagree with the statement not to document the obvious. What is obvious to me or you might not be obvious at all to someone else. Also, I have come across users who to my surprise first read the help topics to understand what they need to do before they did it. Omitting a few steps that someone thinks are obvious, such as clicking Add, makes it very difficult to follow the procedure and logic. Do not assume that the user reads the help side by side with the application open. While that is the likely scenario the user might have navigated to a related topic that now no longer matches the context.

Now to your questions in more or less detail:

If you describe one button, do you necessarily have to describe them all?

Yes! See my point about the reference topics above.

How do you apply rules that ensure the content is helpful without dumbing-down your help in these instances?

Do you mistake being verbose with "dumbing down"? As a user I'd appreciate verbosity more than assumptions that I don't need a few steps in a procedure because the tech writer thought it is obvious.

Do you ever put screen captures in a CSH? (Which, by their nature, assume the user is looking at the interface.) Particularly of buttons?

I try to avoid them because they are taking up a lot of space, they are difficult to localize, and they often have a text label. I include any button images when the buttons only have glyphs. For general overviews over a page or dialog use screen portraits instead. The only exception I'd make is for user defined entries in drop-downs or lists. Example: the user can defined any number of employee types and an employee record can have none, one, or more employee types assigned. By default, the app has no employee types defined. How to clearly explained multi-selection of employee types when especially a new user is looking at an empty drop-down list? In those cases I included an expanded list with multiple entries already selected and made it quite clear that this is just an example. If there was a demo database that someone (trainers, sales) put together I'd use that. If none exists I'd create my own first before using that across the entire documentation.

Another example is a procedure topic that describes how to add, edit, and remove a template.
When you click Add or Edit, both open the Edit template dialog, so other than modifying the steps to say "...to add or edit..." or "...enter or modify..." all the rest of the steps are identical.
Would you create one procedure that includes references to both processes, as above, or create two separate procedures? Or two separate topics?

Two separate processes and two separate topics because any task in CRUD is distinctively different and starts off with different input. As a user who wants to edit a record I would be confused when the procedure describes how to add a record. Use snippets if desired to keep the same steps in one place, but I'd keep them separate. I currently do testing on an application where the edit pages look different than the add pages because the user can execute more functions on existing records (reports, optimization, etc). It might also be possible to have a more concise procedure for editing, but that assumes that the user reading the edit procedure did add at least one of these records previously. I am not convinced that is always the case. In larger operations you have data entry clerks that only add and import stuff while the data maintenance clerks edit and connect records.

If you have a section that is titled "To remove a template" and all the user has to do is highlight the item and click Remove, does that require documentation? In its own section? In its own topic? (Note that the user does need to know that clicking Remove, as the label indicates, does not delete the template, but merely removes it from the current list. Our software, unfortunately, has used these labels somewhat interchangeably, but that is changing.) I advocated for no more information than this, but was out-voted. What would you do in this instance?

One thing upfront...I'd title sections with either the subject as first word or with the activity as first word. So either "Template Removal" or "Removing a Template". When you have a bunch of links somewhere else to these sections it is much easier for the user to browse through them and quickly find what they need. Not the case when the section is titled "To remove a template". The "To" adds no information and I strongly recommend to capitalize key words that name the action and the subject. That also applies to the UI. I always cringe when I see apps that have everything in lower case, it makes reading so much more difficult. Plenty of studies have shown that, no clue why UX designers across the globe just ignore this.

Of course that needs documentation! And yes, in its own topic. If the users decide not to use CSH for that task then power to them. There could be errors or other impacts related to the template removal. Does the template get tied to any other record? If yes, if it is still in use you cannot delete it due to referential integrity. Trying anyways should generate a message. So what now? The user wonders why the delete failed and you have no topic to explain what just happened? The user might wonder if they missed a step or if there is more to than just scrolling to the no longer desired entry, selecting it, and clicking Remove. It is reassuring to see the procedure and finding that I, the user, did nothing wrong. Other things that require documentation is the impact of template deletion. Are these templates used for any scheduled jobs? Does that mean deleting a template will cause the job to fail (and yes, that would be really bad design)? Will deleting the template have any impact on auditing (audit entry referring to a record that no longer exists)? How does the removal impact concurrent scenarios (user A selects the template, user B deletes the template, user A saves the record that now tries to reference a no longer existing record)? I've came across cases where entire portions of the UI were not shown because the last record that could be displayed was deleted (I'd rather see the UI section with a note that there is nothing to show). There may be more. So here I mentioned half a dozen reasons why removing something is not as trivial and obvious as you make it sound. Deletes are evil, they really can mess stuff up. Yes, the procedure to remove something is simple, but the impact is often quite complicated and comes to light in an entirely different part of the application. Ah, come to think, there MUST always be a confirmation message for any delete or removal and documenting what the Yes/No/Cancel/ X button in top right corner do is important.

Am I wrong about this?

IMHO, yes.

I whipped off my reply last evening, so let me clarify about "Don't document the obvious." Do not assume that I mean "Don't document the Add button or Add action...." Rather, I mean, if there is something truly obvious, it does not need detailed documentation. Here is an example: Say that a user deletes something and a message appears that reads "Are you sure you want to delete this thingamagig? Yes / No." To me, that confirmation message doesn't need detailed documentation. It's obvious... Depending on the type of document I'm writing, I might write something like this: "In response to the confirmation message, click Yes". (And, BTW, I make that a snippet so that I can use that same phrasing all over the place." Or I might not document the confirmation action whatsoever as the action the user should take is obvious: either click Yes or click No... (And RamonS, please don't think I'm advocating for not describing, somewhere, perhaps before the step-by-step procedure, what the ramifications of the deletion are.)

Although I certainly don't think that the Microsoft Manual of Style is the arbiter of all things tech writing, I tend to follow the advice they added to the Fourth Edition which is that if the last step in a procedure is to click the OK button, we can leave that explicit step off.

And that reminds me of one a last example. It drives me crazy when I see in a reference topic in which the tech writer, in an effort to document thoroughly, has documented the OK and Cancel buttons. These are obvious and do not need to be documented. The only time they need to be documented in a reference topic is if they behave differently than they usually do.

As a technical writer who documents software applications for a living, I love this thread. I don't agree with everything being said, but I sure am enjoying it.

Ramon, great post. Particularly love the bit about reassuring the user that what they did was the right thing to do.

First question: Who is the audience?
Second question: What is their level of technical expertise?

Explaining the Add button is expected and very helpful to one type of user but might be considered condescending and perhaps even insulting to another type of user. I most often write software documentation for system administrator or network designer level users. These types of people would be insulted if I explicitly described how to save a file (assuming that the option is under the File menu as it is in the vast majority of Windows software), whereas a typical consumer might find it very friendly and reassuring if I told them to save the file and then gave the easy to follow directions.

@Docudramaqueen if the users of your product are end user consumer-types (minimal technical knowledge) then your colleagues might actually be correct in providing screenshots. If the customer typically has basic or higher computer skills, I would strongly vote to leave out the screenshots of basic function and only insert them where they provide real value in explaining something that isn't clear from your text. Hope this helps.

I'm with Ramon on most (all?) of what he said.
I'd especially like to "me too" the bit about reassurance.

Sometimes, I'm the guy who goes to the Help ('cuz there's no other documentation) to find out what I'm GOING to be doing (maybe even why).
Other times, I'm the guy looking for help to find out why things didn't go the way I assumed they would. And how to get out of my current mess.
And yes, if it's important - or I imagine it might be important, and possibly irrevocable - then I absolutely want reassurance that this is what my starting point should look like, and this is what I should see after I've done.... before I take the first step.

In fact, if I'm calling the Help for an app or system, it'll often be just after I backed out of a confirmation dialog.



"Oh....... 'Reconcile' meant 'Delete all the ones that aren't in the other instance'............. oh.......... all my new entries, then.... gone..... just..... just.... gone........"

Nita Beck wrote:I whipped off my reply last evening, so let me clarify about "Don't document the obvious." Do not assume that I mean "Don't document the Add button or Add action...." Rather, I mean, if there is something truly obvious, it does not need detailed documentation. Here is an example: Say that a user deletes something and a message appears that reads "Are you sure you want to delete this thingamagig? Yes / No." To me, that confirmation message doesn't need detailed documentation. It's obvious... Depending on the type of document I'm writing, I might write something like this: "In response to the confirmation message, click Yes". (And, BTW, I make that a snippet so that I can use that same phrasing all over the place." Or I might not document the confirmation action whatsoever as the action the user should take is obvious: either click Yes or click No... (And RamonS, please don't think I'm advocating for not describing, somewhere, perhaps before the step-by-step procedure, what the ramifications of the deletion are.)

I didn't mean write three paragraphs about what the confirmation message entails, but do include it within the step by step instructions in half a sentence. Easy enough to do and nothing where some will stop reading because there is too much blahblah.

Nita Beck wrote:Although I certainly don't think that the Microsoft Manual of Style is the arbiter of all things tech writing, I tend to follow the advice they added to the Fourth Edition which is that if the last step in a procedure is to click the OK button, we can leave that explicit step off.

Not that familiar with the Microsoft Manual of Style, but does it explain as to what the reason is for not adding "Click OK"? Is it that incredibly annoying to read this? It is part of the procedure and it is not our decision to claim that this or that is obvious. Maybe we think that using the ToC of help is obvious or a global site search or the index or whatever else. I find it easier to simply skip parts that I already know than wondering what else the tech writer considered obvious and left out.

Nita Beck wrote:And that reminds me of one a last example. It drives me crazy when I see in a reference topic in which the tech writer, in an effort to document thoroughly, has documented the OK and Cancel buttons. These are obvious and do not need to be documented. The only time they need to be documented in a reference topic is if they behave differently than they usually do.

How do they behave 'usually'? OK buttons constantly behave differently. In some cases all they do is close a read-only info dialog, in other cases they act as submit, in some (badly designed) cases OK means Yes. Just for a matter of exercise describe what the OK button usually does....and I am sure I can find you plenty of examples in common applications where the OK button does not what you described.

In general, I see no harm in stating the obvious, but bigger harm in omitting things just because I think they are obvious or unimportant.

kevinmcl wrote:"Oh....... 'Reconcile' meant 'Delete all the ones that aren't in the other instance'............. oh.......... all my new entries, then.... gone..... just..... just.... gone........"

Well, that was obvious and thus could be omitted, right?

ToddPh wrote:@Docudramaqueen if the users of your product are end user consumer-types (minimal technical knowledge) then your colleagues might actually be correct in providing screenshots. If the customer typically has basic or higher computer skills, I would strongly vote to leave out the screenshots of basic function and only insert them where they provide real value in explaining something that isn't clear from your text. Hope this helps.

Actually, the studies I came across argue that point. Several empirical studies showed that especially inexperienced users are confused by the screen shots in the help thinking that this is the application. So clicking on the buttons does not do anything. Again, I can only recommend reading Andy's blog post from 2006: http://techwritetips.wordpress.com/2006 ... portraits/
If I remember next week I look for the book referencing the studies about the screen shots in help. In any case, there are plenty of equally if not even more convincing reasons to reduce screen shots to a minimum. And if you use them and display only a portion of the UI use the torn edge effect or at least draw a 1px black frame around it unless you capture the entire form. It just looks way better that way.

If the target audience is "especially inexperienced" users, then of course you would write the help in such a way as to be most easily consumed by them. I thought that was the point I was making.

Interesting point about using torn-appearing edges on the screenshots. I think that would be particularly useful.

Let me say that I actually don't disagree with most of what has been said thus far. I fear, though, that I've failed to express myself well and so am being misunderstood.

Of course, the answer must always be "It depends." It depends on the type of document one is writing, on the intended audience, on the purpose. A training guide will offer much more verbose content than will a quick start guide. Documentation for brand-new-never-seen-anything-like-this-before users will need much handholding and much reassuring, whereas network administrators will expect tight, minimal content.

Also, "it depends" can refer to whether or not content will be localized. One of my current projects is a Help system of (so far) about 700 topics that my client plans eventually to localize into 13 languages. With translation vendors charging by the word, I have a professional obligation to my client to produce as clear documentation as I can but in the fewest words possible. It is very important that every word I write pull its weight, and if it doesn't, it should get excised.

Perhaps it might help if I illustrate what I mean by "don't document the obvious" (which I might also express as "don't [necessarily] document the observable").

In the past, for a traditional software user guide/Help system (not training documentation), I would write instructional steps such as this at the end of a procedure: "When finished editing the properties, click OK to save. (Otherwise, to abandon your changes, click Cancel.) The window closes." At some point, I realized that I didn't need to say anything about the Cancel button. I felt reasonably confident that my readers would be able to figure that one out. Next I wondered if I could get rid of "The window closes" as that is exactly what the user expects and is readily observable. Next I wondered, do I really need "editing the properties"? No, so now I've got "When finished, click OK to save." Then I wondered, do I really need "to save", and I determined that it too was most likely unnecessary. I'd whittled it down to "When finished, click OK." And that's probably where I'd leave it for a traditional user guide/Help system. But if I'm writing a quick start guide, I'll probably just write "Click OK" as the last step. I think I'm still meeting the user's needs. And if localization is in play, I'm meeting the objective of helping to reduce its cost.

Regarding the Microsoft Manual of Style suggestion that it's OK to omit "Click OK," their guidance says: "You do not need to end a procedure with "click OK" or "tap OK" unless there is some possibility of confusion." Personally, I think that's good advice. And it's in the spirit of the sage advice from Strunk and White: "Omit needless words." Or as I put it, if a word does not pull its weight -- does not ADD meaning -- then nix it.

My turn, my turn...

What I love about single sourcing is I can document everything and publish only what the user needs.

I don't like screenshots in online (including things like chms) but sometimes a user can benefit from knowing what they should be looking at, or what the screen should look like. I usually have to include the screenshot in the print version so I can hide the online screenshots behind a toggler.

I don't desrcibe all the buttons (for example a dialog box) just the ones for the steps I'm describing. But I do document all the buttons as part of the program documentation and make the information available in the reference material. This process also helps the software testing and debugging process. If I click every button, list control etc as part of documenting its being tested at the same time.

You can conditionalise the obvious steps. For example, in a step by step guide you can say click delete, while the print material can say click delete to remove the current selection, and then describe what happens to the deleted item.

When it comes to presentation print and online users have different needs. Print users could well be away from the PC, reading background material in a quiet location trying to understand something. Online users are using a PC and probably need an instant answer for a narrow range of questions.

Love this stuff

+1 Nita, I consider this a core principle:

Nita Beck wrote:I have a professional obligation to my client to produce as clear documentation as I can but in the fewest words possible. It is very important that every word I write pull its weight, and if it doesn't, it should get excised.

/going slightly off topic >>>/ Although, on a macro level, writing for translation doesn't just mean cutting the word count, it also requires good sentence construction for efficient translation. We can pare sentences down to a minimum for native readers, but this can create ambiguity for translators, which causes delays and errors. Competition: Can anyone beat 32 translations? /back on topic >>>/

+1 Steve, when I'm writing procedures I do this:

SteveS wrote:I don't desrcibe all the buttons (for example a dialog box) just the ones for the steps I'm describing.

I used to provide a reference of every button, but feedback from users was that they skipped it. I now focus on writing workflows for the goals defined in the user needs spec. I cover every workflow, so every button is described in procedural context (except for Cancels and most OKs ).

OK from p346 of Microsoft Manual of Style v 4

"It is all right to omit "Click OK" at the end of a procedure if it is clear that the user must click OK to complete the procedure."

I have a snippet that says "Click OK to close the dialog box and save your changes." which I use in lots of places.

atomdocs, I think we're on the same page.

Writing for translation requires reducing ambiguity. I find the inclusion of "that" and removing possessives really helps when reducing ambiguity. (I first of all wrote "...really helps with this." but then translators work a bit out of context and might misunderstand what "this" means.) And I've written for 31 translations, so I'm close, Nita!

I've recently done a help where there's a "Doing this task..." section, which is in many cases done using a single dialog box, with a sub-topic of "XXX dialog box" which just describes the dialog box. Back to the OP's point I suppose. What should I get the CSH to point to = the "XXX dialog box" topic or just delete that topic completely and link to the "Doing this task" topic? There are other "Doing this task" topics that require the user to open several dialog boxes so I'm happy to have a CSH on each of those, but the simple stuff...?

Anyway, it's Friday. Thank you all for an interesting discussion, always good to see how other TAs tackle the nitty-gritty of what we do.

Like this discussion is showing, there are lots of opinions - but going back to the original post, I think the important part is that you need to be able to back-up whatever approach you're going to take. So to do that, try to do a little research and evidence-gathering, so the next time you get "out-voted", you can back-up your argument and say why your approach is good for your users, so your "vote" should carry more weight than the personal preferences of the people you're discussing it with.

Although be prepared to find out that what might be right for your users, isn't necessarily what you personally think is right!

Unless you're writing "Windows 8 for Dummies" or the like, task-oriented documentation for well-designed software does not need to cover self-explanatory UI elements.

A button is not a task. Neither is a dialog box.

If a dialog box has ten elements and eight of them are self-explanatory (perhaps thanks to some helpful text in the UI), only document the two that aren't.

If a topic, paragraph, sentence, list item, screen shot, or diagram adds nothing to what the user can figure out for themselves by looking at the UI, it should be deleted.

I've inherited entire manuals and online help systems that were nothing but useless narratives of the UI. That was a common problem in the dot-com era when all you needed to get a job as a tech writer was an English degree and a pulse.

As mentioned before, it all depends on the audience. I can only repeat my warning that something that is "obvious" or "self-explanatory" from the point of view of the tech writer who crawls through this and other applications on a daily basis is not as obvious and self-explanatory for others. There is no harm in covering common controls. I'm not advocating to write arias about them, but I have yet to read a compelling reason why inclusion is bad.
As far as screen shots go, I would go light with those, but then again I would write for an audience that does not desired printed or printable output. Anyone who is asked with producing print output should take a different approach.
In general, don't assume things because you are quite likely assuming incorrectly.

Just wanted to say thanks for all your thoughtful replies, many of which were very helpful to my concerns. I get that you need to know your audience, first and foremost. And, of course, there is a big difference in approach, depending on whether you're talking about a procedure or CSH topic, and I may not have made that very clear. Again, thanks for all your input.

I output in PDF. That's what I'm asked for. That's what I deliver.

I use screen caps to break up the text at least, and I hope they serve to illustrate what the text is talking about.