Tech Write Tips

February 21, 2006

Best Practice: Screen Shots vs Screen Portraits

Filed under: Best Practice,Future-proofing,Technology — AndyR @ 1:04 pm

screenshot2.gifWith the increasing tendancy towards re-using help content in a varierty of different contexts, both within the help itself and in different places in the application, we are less sure about how much space we have to display the help content. In the richer interface of windows Vista Screen real-estate is more valuable than ever.

This means that there is less space for screen shot graphics of the interfaces we are addressing in our helps. Where previously we could be sure of the positioning and visibility of our screen shots, this is less and less the case.

screenportrait2.gifThe solution? Copy Microsoft. You may not have noticed the movement away from screen shots in their help pages, but there appears to be a trend away from screen shots towards what we are calling screen portraits.

A screen portrait is a drawn representation of the application window. This enables it to be simplified and small. You currently see them appearing largely in their About topics.

It may seem like extra work to produce bespoke screen representations from scratch. But we suggest that this time is a good investment for the following reaons:

  • Readability: Screen portraits are designed to be recognisable at small sizes, whereas screen shots loose readability when reduced in size.
  • Size: Screen portraits are able to consume less screen real-estate, whereas screen shots demand a large portion of the help pane.
  • Annotations: Screen portraits can have annotations designed in, whereas screen shots have to have annotations super imposed over them which can look clumsey and confusing.
  • Selectivity: The process of producing your screen portraits means that you can assess which graphics are actually needed, and which don’t add anything to the help text.
  • Maintainability: Small adjustments to software don’t result in new screen portraits, whereas screen shots would have needed to be updated.


  1. Another advantage, brought to me by one of our customers:
    No need to create and maintain screenshots for different language versions. One of our customers has some 5000 screenshots and publishes in 4 languages!
    Considerable cost savings, even if the initial effort is bigger to create the portraits.

    Comment by benpal — March 27, 2006 @ 2:50 pm | Reply

  2. What techniques do you use to create those portraits?

    While we include nearly zero screen captures in our online help for the time being, it might be of significant help in terms of single-sourcing if we could include portraits.

    My concern is twofold:

    1) Our screens tend to be either full-fledged web pages, or rather complicated ERP applications with many fields, so I’m not sure how well the context lends itself to screen portraits in the first place.
    2) There is an additional cost in creating the portrait versus the screen cap seems considerable…are there ways to minimize that cost?

    Comment by Andrew — March 27, 2006 @ 4:03 pm | Reply

  3. I think this best practice hits some very valid points. I wonder though, when a screen is too complicated for Help, maybe it is just too complicated to begin with.

    Comment by RamonS — March 27, 2006 @ 6:49 pm | Reply

  4. Ben, interesting aspect of the multiple language example reducing the number of screens you need to maintain. I hadn’t thought of that.
    Andrew, yes I’m not sure how well it pertains to web pages, I wouldn’t have thought you would have screen shots for web pages in the help. Is the help not integrated with the page itself?
    Ramon, Yes there is an overhead, although I find it took me about 20 minutes for the first one, then only 4-5 minuites for subsequent portraits. This has had the side benefit of meaning that I have had to assess which screen shots I really needed. The result being a more streamlined and smaller help.
    One final thought I had, was that someone could produce a tool that creates these screen portraits from the screen captures automatically.
    Thanks for all the comments. I’d be interested in hearing any other thoughts. See you on the Flare Forum.

    Comment by techwritetips — March 28, 2006 @ 7:00 am | Reply

  5. I’m still fairly interested in what technique you use to create the screen portrait — do you build it with an image editor like Photoshop? Perhaps take the original screen an “blur” it until the semantic details are gone, leaving only the structure?

    Regarding web pages and online help: Indeed, we do not include screen captures in our online help, at least not of the web pages (or the Win32 applications either). I was thinking more along the lines of using them for PDF-style documents, but I suppose that full screen captures are perfectly appropriate in that context, and the value of screen portraits over them is significantly reduced.

    Regarding the complexity of web pages and field-/tab-heavy win32 apps: well, when one is writing ERP business software that covers varied market verticals, a lot of information must be packed into a relatively small space. While I may agree that more effort should be taken to simplifying user interface, that is not something in my hands as a writer. 😉

    Comment by Andrew — March 28, 2006 @ 1:18 pm | Reply

  6. Whoops, disregard request for technique. Just started reading your post on it.

    Comment by Andrew — March 28, 2006 @ 1:19 pm | Reply

  7. Great option – I love the localization issue resolution that this brings. Just today one of my clients was speaking about the challenges of localization, different languages, etc.

    Comment by CharlesJet — April 6, 2006 @ 1:45 am | Reply

  8. I wonder though what happens when the GUI changes due to localization and / or design changes. I encounter this constantly with the software I deal with. When translating to German or French we also sometimes face changes in the form layout. Also, unless the screen portraits are without any text, they, too, need to be translated and redone. The how to does not suggest though to add any text.
    As one may notice, I’m not sold on the whole screen portrait idea, nevertheless, I will give it a try in my next project. I’m one of those who have to see it to believe it.
    I also think that one can drop the round edges. When making a screenshot with the standard XP theme the image has the corners filled with some colour, usually one that does not fit the background one uses in the help. The round edges theme is also not available (as a standard option) on non-XP/2003 systems, which after the latest surveys still make up about 50% of business desktops.
    In regards to “While I may agree that more effort should be taken to simplifying user interface, that is not something in my hands as a writer.” Yes, it is. Technical Writers are one more instance in software quality assurance and ought to voice their opposition. Unless a professional ergonomist is on staff, the tech writer has probably the best resources and most experience in regards to usability and readability of any screen display. When you think that a screen or a function is not as good as it could be, you need to file a bug report. It is likely that customers see it the same way. Software engineers make the worst GUIs (see Dilbert).

    Comment by RamonS — April 6, 2006 @ 2:40 pm | Reply

  9. You may also want to check out this post:

    Can I thank you all for the great responses and thoughts. I think this is a topic that we need to carefully consider as we head into providing help with Windows Vista technologies like AP and MAML. It also applies to DITA and DOCBOOK layouts where again space is often at a premium.

    Comment by techwritetips — June 29, 2006 @ 4:48 pm | Reply

  10. I use screen portraits for information about our products, a lot of the products are displays and the information shown can vary hugely while still retaining some common elements. I saved a picture of each display and removed the screen part in Photoshop. I can then just type and arrange any text that varies on separate layers so that I can make it appear or disappear as needed. I find this a LOT quicker than separate screen shots.

    Comment by Robert Hardy — July 3, 2006 @ 2:05 pm | Reply

  11. Well golly gee. Since ahm knot awl versified in uther wayz uh speekin an spellin and such, fer instunce ah doan klaim too no Spanglish er Jurman et al, ahm left uh wonderin if’n these portrait gizmos wood wurk fer all this lokalizin. ahm a thinkin (er wunderin mostly ah rekon) if’n these uther wayz uh speekin an spellin aktually youse nummerz lak we duz. Fer instunce iz uh 1 the same lookin all over? Or izzit difrent lookin ta thoze Jurman folks? If’n thu numberz looks diffrunt to they uther folks woodit wurk?

    Comment by Bubba the teknikal writter — August 31, 2006 @ 4:34 pm | Reply

  12. I see the need to add to my earlier comments. Now that I am working for a different place, the idea of screen portraits comes in handy. We develop help for an application that we do not have access to. We base our documentation on functional descriptions of various detail and accuracy. We do get some early screen shots and mockups from the developers. The general design typically stays in place, but the labels and other text tend to change quite a bit until release. Since we cannot generate screen shots from the “real” application in time, making screen portraits is the best we can do and much better than having nothing.

    Uh, and in reply to Bubba’s post. The 1 looks the same for the Jurmans. Actually, the Jurmans write it as a one, not like those ameriggans who make it look like a lower case l, upper case I, or the | pipe character. And yes, we also cross the seven to prevent confusion. I just don’t get why anyone thinks that writing a one like this “|” is a good idea. But I don’t get that AM and PM crap either and nobody can tell me how many yards are in a mile or how many fluid ounces are in a quart, or why the fluid ounce has nothing really to do with the solid ounce…and don’t get me going about AWG. Sorry, I’m digressing…

    Comment by RamonS — February 12, 2007 @ 3:25 pm | Reply

  13. Thanks for your article by the way If you want to consider ERP system. Free Learning SAP R/3 in a step-by-step online and we provide SAP document and ABAP/4 training online everything we provide free for you. visit

    Comment by mulakan laksamana — November 29, 2009 @ 3:29 am | Reply

  14. Except for localization, if you need pictures of any screen stuff, screenshots are still the best and fastest way to provide graphic information to support text. As for the concerns about screen acreage, cropping is always a good option to slim down and focus the graphics.

    When you add localization, you add several orders of magnitude to the problem.

    As for complexity, I have always believed that complex problems have complex solutions and the documentation matches the software. There is a lot of truth in the old saying, “A picture is worth a thousand words.” But I have always believed that a picture is worth a thousand words only if you have two thousand words to explain it. However, the combination of words with pictures is still unbeatable. But getting back to complexity, I have also believed the simplicity is elegant… I think there is nothing more beautiful that E=mc**2, but there are still several million terabytes in thousands of books to explain those 5 symbols. If you have a complex system, it’s going to take a lotta words to describe is and tell your audience how to use it.

    Comment by Shelley — May 1, 2011 @ 5:54 am | Reply

  15. Just by-the-way, using Microsoft as an example of any kind of good documentation is a lot like using Charles Manson as an example of good birth control.

    Microsoft has the WORST DOCUMENTATION in the world… with the possible exception of Adobe FrameMaker doc. I have yet to find a single Microsoft topic that has completely (or even very effectively) answered any question I’ve ever had about anything in Office or most of their other software. For instance, try to find any documentation about the MS Word ruler, or the symbols on the ruler, or how to use them.

    Comment by Shelley — May 1, 2011 @ 6:05 am | Reply

    • It’s funny isn’t it, I think that MS Office Help is really good. I more often than not find what I am looking for, or find enough to help me work it out for myself. I guess our polarised experiences demonstrates the difficulty we face in creating information that is useful for everyone.

      Comment by David Hutchinson — May 10, 2011 @ 8:00 am | Reply

  16. The key words for me in your response are, “… or find enough to help me work it out for myself.” The problem is that MS Ofice documentation gives you just enough information that “YOU” can work it out after about 2 hours of research and trial and error screwing around. That’s not help, that’s mediocrity… the hallmark of ALL MICROSOFT PRODUCTS.

    Comment by Shelley — May 10, 2011 @ 2:54 pm | Reply

  17. Shelley, I agreed with you completely about the abominable state of any Help for any Microsoft product until just now. In this case, I’m calling it Help even if it’s not embedded in the app; I’m including things like online tutorials. Given the abysmal state of anything that had ever gone before, I was shocked to find the help they’ve provided for migrating to Office 2010 is really good in many instances. I assume they got enough well-deserved criticism such as yours to finally be really stung by it (in the pocketbook, I presume; I don’t believe they respond to anything else) and get serious about improving it. Have you looked at any of the “migrating to Office 2010” stuff? If so, do you agree that it’s better, or is this just me exposing my golly-gee quotient?

    Hmm…come to think of it, I can’t recall anything I’ve looked at in the embedded Help; I think (?) that’s because I have looked, it did help, and I therefore forgot all about it.

    Comment by Lisa Hansen — May 12, 2011 @ 11:57 am | Reply

    • Lisa, I agree with you 100% also. Microsoft has done some pretty amazing migration documentation, especially the Excel “Command Conversion” animations. I am impressed.

      However, I have also tried to use some of their documentation for other aspects of MS Office (can’t remember exactly which, but Macros was one), and found considerable confusion and lack of specific content.

      [BTW, please excuse my unedited reply. I realize that I would not actually publish this in any of my own documentation.]

      Comment by Shelley — May 17, 2011 @ 10:06 pm | Reply

  18. Lisa, I agree with you 100% about the help for the MS Office 2007 and 2010 Help from Microsoft. I was particularly impressed with the dynamic Excel spreadsheets that defined EXACTLY where every command from previous versions is located in the new versions. This has been invaluable to me and everybody I’ve pointed to it. Yes, I too am amazed that Microsoft even had one of their mental midgets who was capable of this kind of thinking. I suppose even morons can have two brain cells that work and produce a miracle once in every thousand years.

    Comment by Shelley — May 12, 2011 @ 3:22 pm | Reply

  19. Wow. Sounds like SOMEbody was fired by Microsoft!

    Comment by Emma at MS — May 17, 2011 @ 9:41 pm | Reply

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Blog at

%d bloggers like this: