17 Nov
2011
17 Nov
'11
11:58 p.m.
Another reason to use markup is because it is
standardized.
With a regular office application, users would spend a lot
of time selecting and making sure font sizes, formatting,
and other things are correct. With markdown you don't do
any of this.
Tech writers don't do that either. :) Tech writers standardize their documents in word
processors and page layout software using style tags. An experienced tech writer never
uses manual formatting. That would be a nightmare! :)
If we use a word processor we create a template for our documents. Ideally the template
disables manual formatting buttons and menu options. Only style tags will be allowed to
format text.
For everyday contributors we let them submit whatever they want. The first thing I would
do on any documentation team is strip the formatting and apply our own template style
tags.
Everyday contributors won't be a part of the internal development team with access to
GIT. These folks are not interested in that. They only want to help with writing.
I think saying "we are not going to use any
markdown
because we dont want our contributors to have to learn
anything, even remotely simple" is a bad philosophy. I
understand if they were going to be using LaTex (quite
complicated) or writing in C++, but markdown is designed
exactly for these sort of things.
Calvin, now you're talking like an uppity propeller head. :D
I've been using desktop computers since 1982. I typed my first "Hello world"
program on a teletype in 1977 or so. Yeah, I'm an old fart. :) In all of those years I
have been observing other people using computers. Most people will not learn anything new
about a computer unless they have good motivation. At work the primary motivation is job
security. At home that motivation is personal projects. Yet even then most people learn
only the minimum they need to finish their tasks.
I have watched experienced tech writers who are good at their job yet are clueless about
computers. Yet they use computers everyday. They don't know how to use Alt-Tab. They
don't know the common keyboard shortcuts for copy, cut, and paste. I've lost count
how many times I have tutored another person and the person hollers at me, "Wait,
wait! How did you do that?" because I performed everything with keyboard shortcuts.
That kind of thing just blows people away.
In other words, you are overestimating what non geek people will do with a computer. :)
People like you and me who find computers fascinating and want to continually learn are
the exception and not the norm. Asking people to help us with documentation means we ask
them to bring their existing skills and not demand anything from them. If we demand
anything then they no longer are being treated like volunteers but unpaid staff.
They'll quit.
I've been changing the engine oil on my vehicles for 30+ years. Most people don't.
Not because they can't or they are dumb. They just have other priorities. Same with
computers. :)
Darrell