git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
AYAbdelrazak Younes <younes@lyx.org>
Date
Jul 31, 2008, 11:24 UTC
Message-ID
<4891A0D0.6060503@lyx.org>
In-Reply-To
<7vy73j418t.fsf@gitster.siamese.dyndns.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.
Previous: Junio C HamanoNext: Stephan Beyer
Message 13 of 39 in “Git Community Book”
  1. Scott ChaconJul 29, 2008
  2. Miklos VajnaJul 29, 2008
  3. Petr BaudisJul 29, 2008
  4. Scott ChaconJul 29, 2008
  5. Junio C HamanoJul 29, 2008
  6. Julian PhillipsJul 29, 2008
  7. Junio C HamanoJul 29, 2008
  8. markdown 2 man, was Re: Git Community BookJohannes Schindelin, Jul 30, 2008
  9. Junio C HamanoJul 30, 2008
  10. Wincent ColaiutaJul 30, 2008
  11. Scott ChaconJul 31, 2008
  12. Junio C HamanoJul 31, 2008
  13. Abdelrazak YounesJul 31, 2008
  14. Stephan BeyerJul 31, 2008
  15. Abdelrazak YounesJul 31, 2008
  16. Abdelrazak YounesJul 31, 2008
  17. Miklos VajnaJul 31, 2008
  18. Abdelrazak YounesJul 31, 2008
  19. Miklos VajnaJul 31, 2008
  20. Junio C HamanoAug 1, 2008
  21. Abdelrazak YounesAug 1, 2008
  22. Thomas RastAug 1, 2008
  23. Abdelrazak YounesAug 1, 2008
  24. Jan KrügerJul 31, 2008
  25. Abdelrazak YounesAug 1, 2008
  26. Dmitry PotapovAug 1, 2008
  27. Abdelrazak YounesAug 1, 2008
  28. Scott ChaconJul 29, 2008
  29. Junio C HamanoJul 29, 2008
  30. J. Bruce FieldsJul 30, 2008
  31. Junio C HamanoJul 29, 2008
  32. Junio C HamanoJul 29, 2008
  33. Scott ChaconJul 29, 2008
  34. Scott ChaconJul 29, 2008
  35. Daniel BarkalowJul 29, 2008
  36. Junio C HamanoJul 29, 2008
  37. Bart TrojanowskiJul 30, 2008
  38. Junio C HamanoJul 30, 2008
  39. Bart TrojanowskiJul 30, 2008

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.