1 of 55

The Seven Righteous Fights

You Should Be Fighting

2 of 55

Heidi Waterhouse

The Lead Developer 2016

#7fights

h.waterhouse@gmail.com

@wiredferret

#7fights

3 of 55

Definition of a Technical Writer:

A master of assembling technical clues into a narrative whole

@wiredferret

#7fights

4 of 55

This truck is stuck in the mud

@wiredferret

#7fights

5 of 55

#7fights

@wiredferret

6 of 55

Example

@wiredferret

#7fights

7 of 55

Tower of translation Babel

@wiredferret

#7fights

8 of 55

5 days

Plus two weeks

@wiredferret

#7fights

9 of 55

Fingers crossed

@wiredferret

#7fights

10 of 55

You cannot fix it later

@wiredferret

#7fights

11 of 55

@wiredferret

#7fights

12 of 55

The Seven Righteous Fights

Localization
Security
Extensibility
Documentation
Affordance
Acceptance
Accessibility

@wiredferret

#7fights

13 of 55

Localization Localisation

#7fights

@wiredferret

14 of 55

Localisation

Don't hard code interface elements

No words in logos or images

Bake in extended character support

15 of 55

Security

#7fights

@wiredferret

16 of 55

The most successful hackers actually look like auditors

@wiredferret

#7fights

17 of 55

@wiredferret

#7fights

18 of 55

Security is neither cheap nor easy,

But it beats the alternative

@wiredferret

#7fights

19 of 55

Encryption

@wiredferret

#7fights

20 of 55

@wiredferret

#7fights

21 of 55

@wiredferret

#7fights

22 of 55

Stop saying that word!

@wiredferret

#7fights

23 of 55

Extensibility

#7fights

@wiredferret

24 of 55

@wiredferret

#7fights

25 of 55

@wiredferret

#7fights

26 of 55

Documentation

#7fights

@wiredferret

27 of 55

Documentation is not state secrets

Documentation is subtle self promotion

@wiredferret

#7fights

28 of 55

User Documentation

Cupcake ipsum dolor sit amet icing. Lemon drops soufflé gummies danish dragée pastry chupa chups brownie. Cheesecake liquorice cake.

29 of 55

Developer onboarding

@wiredferret

#7fights

30 of 55

Production scripts and build sequence

@wiredferret

#7fights

31 of 55

Secretive build engineers

are bad build engineers

@wiredferret

#7fights

32 of 55

@wiredferret

#7fights

33 of 55

Affordance

#7fights

@wiredferret

34 of 55

@wiredferret

#7fights

35 of 55

Some people have more privileges

@wiredferret

#7fights

36 of 55

Homonculus of sensation

@wiredferret

#7fights

37 of 55

Acceptance

#7fights

@wiredferret

38 of 55

Not all Legos have the same job

@wiredferret

#7fights

39 of 55

Shhhhhh

Explain nothing

@wiredferret

#7fights

40 of 55

If you can't hire an expert,

become a student.

@wiredferret

#7fights

41 of 55

Accessibility

#7fights

@wiredferret

42 of 55

@wiredferret

#7fights

43 of 55

@wiredferret

#7fights

44 of 55

8%

of men are colorblind

@wiredferret

#7fights

45 of 55

Screen reader links

Click here. Link. Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link.Click here. Link

@wiredferret

#7fights

46 of 55

@wiredferret

#7fights

This may shock you, but not everyone has broadband, and not everyone has employer subsidies for their cell phone data, and sending people video that starts without their action is RUDE. There are lots of other reasons people don't have infinite data or access to the internet.

I worked on the Microsoft Server team for a while, and I fought and lost a righteous fight there. Lots of the Windows documentation was moving to an on-demand model which allowed us to update and tune the documentation after the software was released. That is a pretty cool idea, but there are exceptions. The most important one is that there are lots of servers that should not be connected directly to the internet and need a firewall with pretty ferocious security rules to keep out web traffic. People who run server rooms are not excited about reading web pages from in there. Letting your server touch the internet is like letting it lick a dirty toilet seat.

But because we as a team had always-on internet and no particular firewall restrictions, none of us were feeling the problem of not having the ability to download documents, so the documents we put up were sadly minimal and server administrators had to switch to another computer to try and get the help for their problem, but the other computer wasn't licensed as a server instance. You see the problem.

47 of 55

TAB

Temporarily Able-Bodied

@wiredferret

#7fights

48 of 55

Now what?

#7fights

@wiredferret

49 of 55

Tactics

Do what you can

Write a coding style guide and follow it
Host brown bag lunches
Pair programming for best practices
Add tests for accessibility and usability
Cultivate diversity and representation on your team
Ask questions

@wiredferret

#7fights

50 of 55

Money is the root

of all business decisions

@wiredferret

#7fights

51 of 55

The Seven Righteous Fights

Localization - Make users comfy
Security - Make users safer
Extensibility - Make code usable
Documentation - Disaster-proof
Affordance - Nudge good behavior
Acceptance - Test with users
Accessibility - Include people

52 of 55

tl;rt

Don't build in compounding technical debt

that you could trivially avoid.

@wiredferret

#7fights

53 of 55

Be productively lazy.

@wiredferret

#7fights

54 of 55

Heidi Waterhouse

The Lead Developer 2016

#7fights

h.waterhouse@gmail.com

@wiredferret

#7fights

55 of 55

Credits

Copyright ceridwen and licensed for reuse under this Creative Commons Licence

By Dori (Own work) [Public domain], via Wikimedia Commons

By Bill Bertram (Own work) [CC BY-SA 2.5 (http://creativecommons.org/licenses/by-sa/2.5)], via Wikimedia Commons

https://www.flickr.com/photos/dvortygirl/

https://www.flickr.com/photos/nez/

By Jonathan Joseph Bondhus (Own work) [CC BY-SA 3.0 (http://creativecommons.org/licenses/by-sa/3.0)], via Wikimedia Commons

By User:Bryan Derksen (Own work) [Public domain], via Wikimedia Commons

Joshua Reynolds [Public domain], via Wikimedia Commons

By Ken Teegardin from Boulder, Boulder (Piggy Bank On Pennies) [CC BY-SA 2.0 (http://creativecommons.org/licenses/by-sa/2.0)], via Wikimedia Commons

By Evan-Amos (Own work) [CC BY-SA 3.0 (http://creativecommons.org/licenses/by-sa/3.0)], via Wikimedia Commons

By Lasart75 (Own work) [GFDL (http://www.gnu.org/copyleft/fdl.html) or CC BY-SA 4.0-3.0-2.5-2.0-1.0 (http://creativecommons.org/licenses/by-sa/4.0-3.0-2.5-2.0-1.0)], via Wikimedia Commons

https://www.flickr.com/photos/31333486@N00/

By Jojhnjoy (Own work, based on the work of Anders) [Public domain], via Wikimedia Commons

By Jericho [CC BY 3.0 (http://creativecommons.org/licenses/by/3.0)], via Wikimedia Commons

@wiredferret