On 17 November 2011 11:10, Kristopher John Gamrat <chaotickjg(a)gmail.com>wrote;wrote: 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 &lt;chaotickjg(a)gmail.com&gt;wrote;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 <http://google.com> is a link to google.com Do you want a new inexperienced user writing your help manual? Calvin Morrison

On 17 November 2011 11:58, Kristopher John Gamrat &lt;chaotickjg(a)gmail.com&gt;wrote;wrote: 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: 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. -- Kristopher Gamrat Ark Linux webmaster http://www.arklinux.org/

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. -- Kristopher Gamrat Ark Linux webmaster http://www.arklinux.org/

On Thursday 17 November 2011 11:50:12 am Calvin Morrison wrote: 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. -- Kristopher Gamrat Ark Linux webmaster http://www.arklinux.org/

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. 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

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. 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