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