Source
r/sysadmin•
zutroy

Documentation - Screenshots vs. wall-of-text

I'm the "documentation guy" at work. Over the last year, I've written hundreds of articles for our team, documenting everything I can think of.

My personal preference is to write everything out in text only, and rarely, if ever, use screenshots. I find them bulky, slow, and just awful looking.

We're using Confluence, and some other people have started adding their own documentation - messy articles full of poorly cropped low-res screenshots. I hate it.

Our documentation is mostly how-to stuff - click here, click there, type this in, etc. Things that are easily explained with words and don't need screenshots.

I've been leading the charge for text-only documentation, but I'm getting push back. So I wanted to toss this out for debate - screenshots or wall-of-text?

Posted May 16, 2014, 10:42 AM UTC

949
DasKapitalist•

Use both. Text instructions so it's searchable and screenshots so you don't have to guess where you need to go for "Step 2: Click edit" on a busy GUI.

29
Prog•

Exactly what I do. Thorough text with screenshots to illustrate.

6
xiongchiamiov•

More importantly, I think, it helps readability when you break up text with images. The whole set of articles is useful, but relevant to this discussion is just the markup section of this post.

Wall of text is never a part of good writing.

Edit: General advice:

  1. Read http://jacobian.org/writing/great-documentation/
  2. Read http://docs.writethedocs.org/en/latest/
  3. Watch http://videos.writethedocs.org/ (or just read Andrew Spittle's notes)
  4. Come join us at Write the Docs next year!
4
[deleted]•

[deleted]

1
killamongaro•

on a busy GUI

That's my biggest thing about screen shots, especially for Windows. Linux, sure, you should be doing everything in the Terminal any way, but Windows usually has you navigating through menu after menu with a bunch of buttons/hyperlinks in each menu, so it makes it easier to navigate through when you have a picture/video to look at.

1
gex80Wannabe VMware Admin•

At this point, there are very few things in Windows that can't be done in cmd or powershell.

1
theevilsharpieJack of All Trades•

Lulz.

Even if Microsoft has finally made their systems fully manageable via Powershell, there are many third party Windows applications that have no Powershell management interface at all.

1
gex80Wannabe VMware Admin•

And that is the responsibility of the third party. VMware and Veeam have no problem doing it for example. So push your vendors to make powershell modules.

1
[deleted]•

[deleted]

18
[deleted]•

[deleted]

8
zutroyOP•

Easy searching was my main reason behind going text-only. I always thought it was just lazy to toss in a giant screenshot.

2
smaug8821Jack of All Trades•

I agree with this. Screenshots should only be there if the wording is confusing.

1
stozinho•

Depends on your audience I suppose. I write a lot of walk throughs for non-technical users, and screenshots are essential.

12
KumorigoeJr. Sysadmin•

Precisely. I've tried text-only walkthroughs here, and got the inevitable calls after, asking "Where am I supposed to click again?"

Need to figure out how to make thumbnails that can expand in a Word doc or PDF...

2
Dday515•

I'm a fan of a two column approach. Have text in the left hand column, explaining what is going on, and include screenshots in the right hand column. I've found that this can be a best of both worlds approach. At the end of the day, however, the text is the most important, as others have pointed out due to its searchability.

10
zutroyOP•

That's an interesting approached that I hadn't considered. I'll have to mess around with a two column layout.

2
cryohazardSCCM Much?•

I do this too with Greenshot or PSR. I love the highlighting, red arrows and obfuscation in Greenshot.

4
xiongchiamiov•

This is the format we use on all our guides: http://www.ifixit.com/Guide/PSP+1000+LCD+Screen+Replacement/1783

I would be remiss if I didn't point out that we sell this software. :)

3
CaelFrost•

Blarg,why no buy button, you'd have to pay me to talk to sales.

3
xiongchiamiov•

All of us technical people hate it, but we've found that people who aren't loose enough with their time on the job to spend an hour chatting with a sales rep are also too stingy with their money, and end up costing more in support costs. :(

Also, if we let you buy it automatically, how are we supposed to milk you for all you're worth? :p

2
sleeplessone•

That's my prefered method. I also try to keep screenshots to a minimum, the key is to keep a nice balance.

2
polyfeuxJr. Sysadmin•

If you use screenshots, make sure you saved them as PNG instead of JPG. With PNG they do not look fuzzy in some areas because of the JPG-compression.

8
After_8•

End user docs = Screenshots.

Docs for other sysadmins = Text. They should be working with scripts and config management systems, anyway, which are text based.

6
GOPWNI have a LinkSkis router•

I don't see why it has to be either/or. You can have awesome documentation that has both text and screenshots. I tend the follow a step by step w/images method

1.Press this

(screenshot)

2.Then this

(screenshot)

And I haven't seen any problems. Just make sure the screeshots aren't low res garbage.

5
5y5tem5•

A quick way to do this (on Windows) is to use psr.exe(problem steps recorder) walk through the steps and then just edit the report.

7
R34p3r•

A.m.a.z.i.n.g.

1
mikejt2Jack of All Trades•

That is awesome! Did not know about it!

1
GOPWNI have a LinkSkis router•

I actually just use the Snipping Tool because PSR is a pain if you have multiple monitors, plus I like using the highlighter in the Snipping Tool to pinpoint exactly what I'm showing them.

0
5y5tem5•

To be honest I do it on a vm so I can bring the resolution down to something more manageable.

1
nizzy1115IT Manager•

That is what I do too.

1
become_taintless•

I use screenshots and text; if it's a 30 page document describing a particularly nasty setup routine, I like having thumbnails (and the online version of the same documentation lets you click the thumbnails for the large version.)

Other than the philosophical preamble (what's this system for? why are we doing this seemingly exotic thing this way?,) I tend to only actually document the values that need to be typed in (or notation that certain values are left blank) otherwise the documentation becomes a wall of text.

In Confluence, make a two column table with headers. Label the left column Instruction and the right column Illustration; drop high res screenshots in the right cell of each row (then click it and resize it to make it smaller) and instructions for that screen on the left hand side.

Make sure you use the {toc} macro and h1. h2. h3. to create subheadings.

Here's a screenshot of part of the documentation we made for the lost souls who are forced to continue using a FoxPro application for part of their job while we finish developing the replacement:

http://i.imgur.com/Y2UhsUI.jpg

4
TechIsCoolJack of All Trades•

FoxPro is a text-based procedurally oriented programming language and DBMS, originally published by Fox Software and later by Microsoft, for MS-DOS, Windows, Macintosh, and UNIX. The final published release of FoxPro was 2.6. Development has continued under the Visual FoxPro label, which in turn was discontinued in 2007.

http://en.wikipedia.org/wiki/FoxPro

1
become_taintless•

The final published release of FoxPro was 2.6.

The absolute latest version was 2.6a, released in 1996!

Thank god I have nothing to do with the application itself (which, by the way, has been actively maintained until just recently.)

1
DerStroNetwork Engineer•

When writing up documentation for our tier 1 helpdesk I will always write everything out in text form, but also fully screenshot the entire process as a sort of secondary measure. I agree that they can be ugly and annoying if done incorrectly, but I've found that keeping all the images the same size, resolution high, and allowing the end user to completely ignore them if they choose has lead to a pretty high success rate. Everyone has a different learning style, and while I agree a text only document might be quicker to go through for me, some users will find a well done set of screenshots a godsend if they're in a pinch and just unable to grasp a wall of neatly formatted text.

3
XibbyVehicle sold seperatly.•

I always do text first, and add screenshots for clarity if needed. This would be a good compromise in your case I think. Most of the documentation I do for IT staff is just text unless I feel it needs visual clarification. If documentation is for end users, I do text first then add the screen shots so things are "if you can't follow this there is no force in the universe that can help you" clear. We're also using Confluence. I make good use of footnotes and other macros. Really slick.

When I do screen shots they are full res screen shots properly cropped and quality preserved with Acorn (Mac OS) or Paint.NET (Windows) because fuzzy screenshots are worthless.

Most of the time I capture and mark up screenshots in Skitch (from Evernote.) Makes it easy to add circles, arrows, labels, etc. to the screenshots and I don't have to worry about where they were saved, getting them from one computer to the other, etc.

3
5k3k73k•

This shouldn't be an either or proposition, use both. The information is most likely going to be redundant but text is searchable and people are visual animals. Learn Photoshop or GIMP to nicely crop only the relevant information.

3
mauirixxxLone Wolf Sysadmin - Forever alone.•

I'm a fan of both as well. I tend to put the text down as click here, enter this - and then afterwards I'll include a screenshot of just WHERE that text goes, and what the completed dialogue box should look like before you click next/OK/Save/Finish.

Best of both worlds, though I could probably get by with 0 screenshots ....

1
DarthKane1978Computer Janitor•

I find looking at pictures with one or two sentences explaining the process to be less taxing on my eyes and takes less time than reading a paragraph or two. Plus I am sort of dyslexic....

3
[deleted]•

[deleted]

2
realged13Netadmin•

I am the documentation guy as well. That was one of the first tasks at my new job was to get stuff documented and organized.

I explain everything through text, bold the items that are important an accompany certain steps with screen shots. Everything that you need is written in text and searchable. However, sometimes there is a lot to enter, so I will take a screenshot with all of the information entered just as a reference point. You could take out all the pictures and still complete the task.

2
[deleted]•

[deleted]

2
rapcatJack of All Trades - Master of None•

My admin documents are text 99%. My helpdesk documentation is a healthy 60-70% text.

Reason being is that a sysadmin would be able to read my text and have a pretty good understanding of where he/she needs to go to complete this task. I give a general overview of what needs to be done and the sysadmin can take the route they want to in order to finish that task. If they want to use the GUI. Fine. If they want to use PS. Fine. If they want to write some scripts to automate the task. Fine.

A helpdesk person or a user using the helpdesk documents would need pictures as a sign of reassurance they are at the correct step. Everything needs to be spelled out as well.

2
Ron_Swanson_Jr•

I think people learn better when you explain it to them with text and they have to find what they need to click on, type, etc. If I really need to dumb it down, I will screenshot EVERY. LAST. DIALOGUE. BOX/BUTTON/MENU, etc. Basically, consider the audience. If it's meant to be a training document, text with a few screenshots. If it's meant to teach idiots how to reset their RSA token passphrase........screenshots all the way.

2
gakuleSysadmin•

Whenever I do documentation, I typically write it with a few objectives in mind: 1) Someone who has never used a computer before can follow the instructions and not have a problem. 2) There is no room for interpretation on what you should be doing, as you have thought out every possible scenario. To me, documentation writing is like programming... you have to plan for everything someone will possibly do to get lost.

Often times, this requires screenshots. People love pictures, and it's easier to "read" a screenshot than a big wall of text. It's not searchable, no, but if you include text with your screenshots then you shouldn't have a problem. I also tend to make hyperlinks within my documents when creating them, and include a table of contents in the very beginning.

2
SysAtMNSysadmin•

You need to find a happy medium. Both text and screenshots are effective but primarily at different things.

I'd suggest establishing a standard on when to publish a screenshot and when not to. For example, if you have a screenshot that can simultaneously display 3+ of your steps then go ahead and use it. Likewise if a single screenshot can eliminate 3+ steps it should be used. Whatever you decide to do the screenshots should only complement the text in the documentation, not replace it entirely.

Keep in mind that people learn from different types of visual aids. Some prefer text for reading and searching (ex. your fellow sysadmins) while others prefer images, maps and screenshots (ex. your HelpDesk). Heck some people don't prefer any visual aids and would rather you demonstrate in person or walk them through he process on the phone (your hands on and audio learners).

The best documentation is going to get your message across to all kinds of learners efficiently and effectively so you do not have to take calls or go back to explain yourself over, and over, and over again.

2
[deleted]•

[deleted]

2