Dark Patterns and Microaggressions in Documentation by limeonaire https://padlet.com/limeonaire/z9yclryoyqox37je Things that frustrate us or or slow us down when we encounter them en-us 2021-03-30 18:48:08 UTC 2021-03-31 21:09:53 UTC hello@padlet.com https://padlet.net/icons/png/1f4ab.png e.g., path to resources is broken in instructions limeonaire https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1369339665 2021-03-30 18:57:47 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1369339665 e.g., assuming everyone who uses a tool is familiar with an older version of the tool limeonaire https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1369344146 2021-03-30 18:59:00 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1369344146 e.g., "I never thought anyone would try to use it that way." limeonaire https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1371631811 2021-03-31 13:05:21 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1371631811 e.g., forgetting that new staffers from another region won't be familiar with specific cultural terms limeonaire https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1371639969 2021-03-31 13:07:35 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1371639969 e.g., every instruction states, "He should then..." or even "He or she should then..." limeonaire https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1371649142 2021-03-31 13:10:03 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1371649142 e.g., assuming it would be too much trouble to write inclusive CMS instructions for older folks with a different frame of reference limeonaire https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1371653687 2021-03-31 13:11:15 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1371653687 e.g., the documentation itself is inaccessible to folks using screen readers limeonaire https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1371658626 2021-03-31 13:12:34 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1371658626 Too much detail can also be a problem. It can be overwhelming. susannahlocke https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372989912 2021-03-31 18:39:32 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372989912 You must be logged in to see the docs, so you can't get help with logging in. https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372990838 (A real problem in my org, for a long time!)]]> 2021-03-31 18:39:49 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372990838 Assuming everyone understands technical jargon https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992161 2021-03-31 18:40:10 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992161 Hard to read on mobile devices https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992215 2021-03-31 18:40:11 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992215 Using the terms "look," "see," or "view" when you mean "read" https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992454 Different people use different tools to read]]> 2021-03-31 18:40:15 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992454 Overly technical language and words that a lot of people aren't familiar with, especially if non-technical people (e.g edit + junior level folks) are using the documentation. https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992468 2021-03-31 18:40:16 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992468 using jargon or terms not everyone may know ashiu4 https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992473 2021-03-31 18:40:16 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992473 What do you do with outdated or no longer relevant documentation? https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992907 We have a huge source of documentation for our CMS users and we add new documentation as new features are added, but never ever go back and groom the already existing documentation that is still searchable.

]]> 2021-03-31 18:40:23 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372992907 Third party tech changes https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372993184 Documentation refers to third-party tech you don't control ... and then the tech changes.]]> 2021-03-31 18:40:28 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372993184 idioms and slang can be difficult, even for people with a great grasp of the language susannahlocke https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372993278 2021-03-31 18:40:29 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372993278 Assuming that people are reading docs in a linear way and not skimming through to find the information that they need. morgancohn https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372993561 2021-03-31 18:40:34 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372993561 Included videos don't have (good or any) captioning https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372994240 2021-03-31 18:40:46 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372994240 Refers to other knowledge resources that may not be acessible to every reader. Broken links / gated content in corporate network https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372994895 2021-03-31 18:40:57 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372994895 Assuming people have access to equipment/resources they may not have or be able to afford https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372995140 2021-03-31 18:41:02 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372995140 Difficult to find docs; not all in a central place or not well organized ashiu4 https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372995154 2021-03-31 18:41:02 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372995154 Biased imagery deads2 https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372995219 E.g. science texts with only images of men practicing science.]]> 2021-03-31 18:41:03 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372995219 Assuming excellent internet access-this can be a problem for low-income, geography, etc. https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372995710 2021-03-31 18:41:11 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372995710 Being overly specific (e.g., style guides that repeat the dictionary entries for various things) limeonaire https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372996447 2021-03-31 18:41:19 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372996447 Mentioning a tool, or method, but not including a guide or link to a refresher for those not acquainted. hyselemon https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372997181 2021-03-31 18:41:31 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372997181 Learning styles and the assumption if you wrote they will retain the instruction vs people who need to hear, see, or physically do it first https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372997650 2021-03-31 18:41:39 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372997650 Font is too damn small deads2 https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372997873 (General accessibility overlap)]]> 2021-03-31 18:41:43 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372997873 Writing instructions in terms of personnel rather than roles, assuming people will stay on forever and the reader knows who that person is. https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998001 Example: Ask Meghan if you need help vs. Ask the Director of Marketing if you need help]]> 2021-03-31 18:41:46 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998001 Visuals https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998046 Using process/architecture maps to provide lean visualization for users that may learn differently than others

]]> 2021-03-31 18:41:47 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998046 Getting people to read it https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998072 (Instead of just DMing you every time they forget how to do something.)]]> 2021-03-31 18:41:47 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998072 words like 'master' or color words that denote positive/negative https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998117 2021-03-31 18:41:48 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998117 colorblindness can be a problem for documentation that uses red to highlight issues. https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998253 2021-03-31 18:41:51 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998253 Cultural references that may not be known by everyone https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998797 2021-03-31 18:42:00 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372998797 Not including where to find certain folders, documents, etc. https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372999151 2021-03-31 18:42:06 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372999151 Assuming people know where to go with questions https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372999360 2021-03-31 18:42:10 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372999360 Swearing and other saucy content-- makes you sound cool in techworld and journoworld, but can also be offensive susannahlocke https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372999374 2021-03-31 18:42:10 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372999374 Ownership https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372999405 Did one person or team write it? If so, is there a plan to maintain it once they're gone or off to the next thing? So much documentation is simply orphaned.]]> 2021-03-31 18:42:11 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372999405 Not having a centralized place for documentation https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372999428 2021-03-31 18:42:11 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1372999428 What's the right format for the audience? ashiu4 https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000054 Documents might seem overwhelming or go un-used. other possible formats: slide deck, short demo videos...]]> 2021-03-31 18:42:22 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000054 Ignoring that some people use they/them pronouns. It is most accessible to use plural pronouns to write gender inclusive docs. https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000079 2021-03-31 18:42:23 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000079 People know how to access all of the tools and/or personnel they made need to complete a task. https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000090 2021-03-31 18:42:23 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000090 Screenshots are helpful, but can go out of date quickly https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000093 2021-03-31 18:42:23 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000093 Discoverability deads2 https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000285 Does it appear in search results, etc?]]> 2021-03-31 18:42:27 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000285 Women being seen as the note takers/defaulting to asking them to update docs that benefit the entire team https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000540 2021-03-31 18:42:31 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373000540 Hosting the documentation https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373001821 Do you need to be on the VPN to access it?
Is it password protected?
Is it in house or a third-party?]]> 2021-03-31 18:42:54 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373001821 When the same instructions don't apply to everyone https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373002151 ie, an open-source and hosted version of your product]]> 2021-03-31 18:43:00 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373002151 Product managers writing documentation for their product or feature have a very biased view https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373002443 PMs spend their entire work week looking and interacting with their product and feature. This impacts how they come at their documentation. You need to remember that almost no one has as much context as you.]]> 2021-03-31 18:43:05 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373002443 ACRONYMS ARE A PROBLEM https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373002671 2021-03-31 18:43:09 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373002671 Video goes out-of-date so quickly, and is often inaccessible, and then you have to rerecord a video segment or entire video if it changes limeonaire https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373002681 2021-03-31 18:43:09 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373002681 Not accounting for roles and permissions in docs - can the person reading the doc even access the thing morgancohn https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373002891 2021-03-31 18:43:13 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373002891 Links that break https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373004337 Linking something crucial or to a bigger explainer that eventually doesn't work]]> 2021-03-31 18:43:35 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373004337 Older users in my experience often use tablets and can't see/use multiple screens at the same time. https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373004555 2021-03-31 18:43:38 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373004555 Cultural assumptions like "going to the bar" deads2 https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373005140 2021-03-31 18:43:48 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373005140 People https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373005832 Referring to specific people as a resource for "more information"]]> 2021-03-31 18:44:01 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373005832 The "not another tool" problem https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373005877 Adoption of a documentation tool, if it's different from the tools people are already using.]]> 2021-03-31 18:44:02 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373005877 Docs that aren't searchable limeonaire https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373006430 2021-03-31 18:44:11 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373006430 directions in which people navigate or read https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373007105 2021-03-31 18:44:20 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373007105 Not including instructions for different devices/browsers/etc. https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373007183 ^Sometimes because the product hasn't been tested on other devices/browsers/etc.]]> 2021-03-31 18:44:21 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373007183 putting the documentation on a platform that not everyone uses https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373008257 2021-03-31 18:44:40 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373008257 For language, writing in a tone that's welcoming and interested in guiding, not just sounding smart. hyselemon https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373008922 2021-03-31 18:44:49 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373008922 Random capitalization https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373009438 Can be so confusing]]> 2021-03-31 18:44:58 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373009438 Assuming your reader knows how to access the documentation, or easily navigate through the document/storage system https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373009719 2021-03-31 18:45:02 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373009719 Assumption that all people know and are aware of industry frameworks. https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373010482 2021-03-31 18:45:15 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373010482 font types and colors that appeal to masculine and feminine sensibilities https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373011053 2021-03-31 18:45:25 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373011053 Corporate-speak susannahlocke https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373011078 2021-03-31 18:45:26 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373011078 Asking the only person of color in a group to check to make sure the language/docs are acceptable to that affinity group https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373012323 2021-03-31 18:45:44 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373012323 Not stating at the top who these documents are for. hyselemon https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373023252 And for what purpose (by the end of this, you should have a good idea of...) ]]> 2021-03-31 18:48:49 UTC https://padlet.com/limeonaire/z9yclryoyqox37je/wish/1373023252