trinity-devel@lists.pearsoncomputing.net

Message: previous - next
Month: November 2011

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

From: Darrell Anderson <humanreadable@...>
Date: Thu, 17 Nov 2011 09:17:49 -0800 (PST)
> *this is bold*
> _this is italic*
> 
> # This is my top header
> ## second header
> ### third
> 
> * here is a list iten
> * here is another list iten
> * here is the third and final item

I appreciate your sincerity here, but most everyday users who know only WYSIWYG freak out with any markup language. Most people I know consider me a computer geek --- yet I dislike working in raw markup. I still refuse to use asterisks and underscores to symbolize bold and italics. But like I said, I'm an cantankerous old fart. :)

I think you are still focusing on other people merging revision changes upstream like a developer does with software. That is not how the documentation process will work. We'll accept revision changes from users in any commonly used format. The Trinity documentation team will perform the actual updating to satisfy internal style guides. The tools we are discussing are for the documentation team, not outside helpers. But the documentation team has limited time too. Selecting common tools that everybody will use reduces overhead and anxiety.

> Do you want a new inexperienced user writing your help
> manual?

Yes! They are the best people to help with documentation. The people who develop software are too close to a project to see both the forest and the trees. People unfamilar with the software arrive with fresh eyes about software. When something breaks or does not work as they perceive they grab the manual. When the manual fails they get frustrated. An experienced tech writer learns to catch those potential pitfalls but nobody catches them all. Newbies catch everything. :)

As a side note, not including newbies is why a lot of free/libre software fails to make the mark. Beta testing is limited to fellow geeks. True usability testing grabs people off the street, people unfamiliar with the software. I have been around computers for three decades and tech writing for two. I can almost make engineers and developers cry because through those years I have developed a knack for thinking like a newbie when I test products. Actually most of them don't cry --- they mutter four letter words at me. :)

Darrell