Message: previous - next
Month: November 2011

Re: [trinity-devel] Trinity User's Guide

From: Darrell Anderson <humanreadable@...>
Date: Thu, 17 Nov 2011 08:58:21 -0800 (PST)
> 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. :)