On 17 November 2011 11:10, Kristopher John Gamrat chaotickjg@gmail.comwrote:

On Thursday 17 November 2011 10:25:58 am Marvin L. Jones wrote:

...

On Thu, 17 Nov 2011, Calvin Morrison wrote:

...

But if we are suggesting that our users are incapable of editing markup of any kind, I seriously doubt their ability to use patch, diff, and git commands.

You expect _users_ to be doing patch, diff, and git commands? I don't think so.

If the website view of the git repository allows people to download files directly, they don't need to use git. They can just submit it to us and we can upload it to git. It would just be easier for those who do know git.

...

Is it too late to put in a request to do documentation in WordStar? Now, there's a markup language _I_ know! :-) (I have it running here on Ubuntu 10.04 LTS...)

I don't think we'll accept any requests for any markup languages. If you can find something that'll do the job efficiently without making it any harder than opening a standard word processor, then it's not too late.

A standard word processor? you mean libreoffice.

I've been double checking and I can't find fodt support in Abiword, msoffice, and I don't think Word Perfect does it either.

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.

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.

I dunno,

Calvin Morrison

On 17 November 2011 11:42, Kristopher John Gamrat chaotickjg@gmail.comwrote:

On Thursday 17 November 2011 11:25:23 am Calvin Morrison wrote:

...

On 17 November 2011 11:10, Kristopher John Gamrat

chaotickjg@gmail.comwrote:

...

...

On Thursday 17 November 2011 10:25:58 am Marvin L. Jones wrote:

...

On Thu, 17 Nov 2011, Calvin Morrison wrote:

...

But if we are suggesting that our users are incapable of editing markup of any kind, I seriously doubt their ability to use patch, diff, and git commands.

You expect _users_ to be doing patch, diff, and git commands? I don't think so.

If the website view of the git repository allows people to download

files

...

...

directly, they don't need to use git. They can just submit it to us and we can upload it to git. It would just be easier for those who do know git.

...

Is it too late to put in a request to do documentation in WordStar? Now, there's a markup language _I_ know! :-) (I have it running here on Ubuntu 10.04 LTS...)

I don't think we'll accept any requests for any markup languages. If

you

...

...

can find something that'll do the job efficiently without making it any harder than opening a standard word processor, then it's not too late.

A standard word processor? you mean libreoffice.

LibreOffice Write, MS Word, etc. It just lets you do normal word processing.

...

I've been double checking and I can't find fodt support in Abiword, msoffice, and I don't think Word Perfect does it either.

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.

How will it look right if it's not formatted correctly? Even with HTML (which is markup), you need to format with things like size, fonts, and colors.

My Mistake, I meant to say "markdown". In which you do almost no specific formatting, no sizes or colors. This is all done when you generate the files the only markup you need for markdown is very basic. for example:

*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

http://google.com is a link to google.com

...

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.

People already need to learn TDE, maybe even the computer. Those of us who grew up with computers and/or using Linux for awhile won't find that hard, but new inexperienced TDE users who want to contribute as a way of saying thanks are going to spend enough time getting adjusted. They might only learn one or two apps really well and be trying to learn everything else they need. We do want them to learn, we don't want to put them into overload.

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

Calvin Morrison

On 17 November 2011 11:58, Kristopher John Gamrat chaotickjg@gmail.comwrote:

On Thursday 17 November 2011 11:50:12 am Calvin Morrison wrote:

...

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

I was contributing to documentation over at Ark Linux within a month after I started. It wasn't much, and most of it was adding details to existing documentation, but I did contribute. That's what most inexperienced users will do if they do contribute: add in details. That's quite useful to have: since most of us have been doing awhile, it's hard for us to write from a newbie perspective, so we might leave out important details or not be clear. A new user who's reading that might get just enough detail to figure it out on their own and want to help improve the article.

I'll respond to both here.

If users are sending in data and we are going to reformat it, it doesn't matter if we use markdown or not.

Again if this is going to be very collaborative as Piki suggests, we might as well employ the wiki we already have in place.

Calvin Morrison

On Thursday 17 November 2011 12:17:00 pm Timothy Pearson wrote:

Overruled. :-) The consensus here (which I agree with) is that no markup languages are needed or desired. This documentation could potentially grow to the size of a small book--can you seriously even imagine trying to edit that for clarity, let along grammatical errors, without a word processor? There is a right tool for the job, along with a bunch of wrong, but workable, tools. Let's use the right one!

We will use the flat ODT format in GIT. I will work on getting automatic builds both to "real" document formats (PDF, PostScript) and to HTML. Help is welcome here; basically I just need the command line to pass to LibreOffice to make it spit out such documents, especially on the HTML end.

As long as there's public read access on the web site, that shouldn't be a problem. There was a comment earlier that people won't want to learn (or won't understand) version control, so making it downloadable in a browser without a "git clone" is desirable. If that's possible, I'm all for using git for the manuals.

I personally don't see why it's important to use markup, markdown, word processors.

The main thing is to make it easy to contribute. People don't want to learn more than they need to in order to contribute. Expecting them to is completely stupid. Do the most amount of work with the least amount of effort is always the best way of doing things. As such, people won't want to learn any special formatting language just to write something they can do in a word processor. That's what they already know.

Having people contribute stuff and having us format it into markdown would be more effort for us. Provide them an ODT they can open at home and they can format it themselves. Of course, that doesn't take into account stupidity, but we can make guidelines for that so things we get are sensible enough that it minimizes effort of correcting it.

If we do use some sort of markup, I think MediaWiki would be our best bet. That's what Wikipedia uses, so most people will already be familiar with it. We could even set one up separate from the main wiki just for the manuals. If we keep the database and files completely separate, it shouldn't be too hard to delete it later if we decide to.

The main problem either case is converting it to whatever other format. PDFs shouldn't be a problem. But then there will be formatting them for the TDE Help system, and HTML.

Since I already know enough HTML to do normal documentation, and I already have an IDE that I'm well adjusted to, I wouldn't mind helping on that respect. I can also help writing the manuals. If I have to learn something new to do that when I can easily do it with what I already know, count me out.

On Thursday 17 November 2011 11:50:12 am Calvin Morrison wrote:

My Mistake, I meant to say "markdown". In which you do almost no specific formatting, no sizes or colors. This is all done when you generate the files the only markup you need for markdown is very basic. for example:

*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'll add that after MediaWiki, I find that fairly simple, but unless I have to, I don't want to type more than needed. Pushing shift+8 before each list item is harder than clicking the list button in LO Writer, pushing enter after all items, then click the list button again. Shift+8 is easier than the button only for a really short list, but for long lists, it's a bit cumbersome.

Also, being used to CTRL+I, CTRL+B, etc., and seeing my changes instantly, I'm likely to forget something obvious. I do that all the time with HTML. For lots of markup or markdown code, my eyes would go crooked finding that one mistake. I think others share that same experience.

I think the "shorter is easier" thing will, for most people, apply to markdown, while "longer is easier" will be for word processors.

*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

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