From mboxrd@z Thu Jan 1 00:00:00 1970 From: Abdelrazak Younes Subject: Re: markdown 2 man, was Re: Git Community Book Date: Thu, 31 Jul 2008 13:24:00 +0200 Message-ID: <4891A0D0.6060503@lyx.org> References: <20080729170955.GK32184@machine.or.cz> <7vwsj4edm1.fsf@gitster.siamese.dyndns.org> <7vy73j418t.fsf@gitster.siamese.dyndns.org> Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Cc: Johannes Schindelin , Julian Phillips , Scott Chacon , Petr Baudis , git list To: Junio C Hamano X-From: git-owner@vger.kernel.org Thu Jul 31 13:25:23 2008 Return-path: Envelope-to: gcvg-git-2@gmane.org Received: from vger.kernel.org ([209.132.176.167]) by lo.gmane.org with esmtp (Exim 4.50) id 1KOWHS-0007Ll-SH for gcvg-git-2@gmane.org; Thu, 31 Jul 2008 13:25:15 +0200 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751847AbYGaLYN (ORCPT ); Thu, 31 Jul 2008 07:24:13 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1751844AbYGaLYM (ORCPT ); Thu, 31 Jul 2008 07:24:12 -0400 Received: from smtp4-g19.free.fr ([212.27.42.30]:42595 "EHLO smtp4-g19.free.fr" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751172AbYGaLYL (ORCPT ); Thu, 31 Jul 2008 07:24:11 -0400 Received: from smtp4-g19.free.fr (localhost.localdomain [127.0.0.1]) by smtp4-g19.free.fr (Postfix) with ESMTP id 62C003EA100; Thu, 31 Jul 2008 13:24:05 +0200 (CEST) Received: from [192.168.0.10] (gre92-10-88-181-30-42.fbx.proxad.net [88.181.30.42]) by smtp4-g19.free.fr (Postfix) with ESMTP id D79433EA0C4; Thu, 31 Jul 2008 13:24:04 +0200 (CEST) User-Agent: Thunderbird/3.0a2pre (Windows; 2008072800) Newsgroups: gmane.comp.version-control.git In-Reply-To: <7vy73j418t.fsf@gitster.siamese.dyndns.org> Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Archived-At: 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.