Re: markdown 2 man, was Re: Git Community Book

[Abdelrazak Younes <younes@lyx.org>]

Hello,

Sorry for this irruption on this list. I am just a git user and casual 
reader of this list. I thought I could share my thoughts about this as I 
know a bit about document creation. Please ignore if this is not 
appropriate.

Disclaimer: I am involved in LyX development, so anything I said will be 
biased :-)

Junio C Hamano wrote:
> As I am not in "graphics and screencast" camp, I may probably not be able
> to offer much help improving his book, and I suspect some people on this
> list might feel the same way.  But that's is Ok --- we are not dumping the
> User Manual.

IMHO, documentation is best written by users, not developer. So, again 
IMHO, anything that could accommodate the _user_ for document writing 
should be done. An enthusiastic user is more likely to spend time 
writing documentation than a developer. For example, within the LyX 
project, most writers and translator are not developer.

Asciidoc or Markdown are tools that accommodate the _developer_, not the 
user. I understand that these markup language are ideally suited for in 
source documentation (thought I personally much prefer Doxygen). I also 
understand that launching a different application just to modify a line 
or two in the user manual seems cumbersome for the developer but IMHO, 
if you're serious about working on the documentation, you are not going 
to change a line or two and launching an external application is no big 
deal.

Now, about my shameless plug: LyX is ideally suited for structured 
documentation writing :-)

Abdel.