Comments on: How to write a better book (or just better docs!) http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/ Thinking about programming in new ways Wed, 28 Jul 2010 19:00:53 +0000 hourly 1 http://wordpress.org/?v=3.0 By: Tobin Harris http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-274768 Tobin Harris Wed, 19 Nov 2008 15:58:06 +0000 http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-274768 I've been curious about this too. I've settled on Scrivener (OSX) which can export to MultiMarkdown ready for LaTeX. I can generate a PDF preview of the book in about 5 seconds and a few keypresses. And, MultiMarkdown also allows you to go to HTML or RTF. Next, I next need to work out how to pull source code in for code listings in the book. I'm thinking of writing a script that will detect special comment tags in my code and then import them in. I'm really curious about how the Pragmatic Press are doing things. Does anyone know what they use? I’ve been curious about this too. I’ve settled on Scrivener (OSX) which can export to MultiMarkdown ready for LaTeX. I can generate a PDF preview of the book in about 5 seconds and a few keypresses. And, MultiMarkdown also allows you to go to HTML or RTF.

Next, I next need to work out how to pull source code in for code listings in the book. I’m thinking of writing a script that will detect special comment tags in my code and then import them in.

I’m really curious about how the Pragmatic Press are doing things. Does anyone know what they use?

]]> By: Christopher Arndt http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-142265 Christopher Arndt Fri, 14 Mar 2008 23:11:12 +0000 http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-142265 The new Python standard documentation system, sphinx, already has directives to include code blocks from external files. Maybe we should have a look at it, how easy/hard it is to expand it's capabilities to do what you propose. It produces beautiful docs from the rest sources and has good support for both reference and tutorial style docs. The new Python standard documentation system, sphinx, already has directives to include code blocks from external files. Maybe we should have a look at it, how easy/hard it is to expand it’s capabilities to do what you propose. It produces beautiful docs from the rest sources and has good support for both reference and tutorial style docs.

]]> By: Jean http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-141982 Jean Fri, 14 Mar 2008 09:40:08 +0000 http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-141982 Hi, I know that Bruce Eckel uses its own method and python scripts to extract code from his "Thinking in Java" book and test them. You might want to contact him. Best regards, -- Jean Hi,

I know that Bruce Eckel uses its own method and python scripts to extract code from his “Thinking in Java” book and test them. You might want to contact him.

Best regards,

– Jean

]]> By: Mark Ramm http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-141096 Mark Ramm Wed, 12 Mar 2008 14:15:45 +0000 http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-141096 Rene, Yea, doctest is great. But I can' actually imagine trying to write an entire book in doctest -- there are just too many limitations. Particularly when it comes to write extended tutorials on how to write large projects. You really can't do that all in an interpreter session. And even for smaller documentation projects, doctest can sometimes feel a little awkward as a full documentation tool. doctest's use of the interpreter session metaphor can force your example code to look strangely unlike the code you would actually write when using the library. Rene,

Yea, doctest is great. But I can’ actually imagine trying to write an entire book in doctest — there are just too many limitations. Particularly when it comes to write extended tutorials on how to write large projects. You really can’t do that all in an interpreter session.

And even for smaller documentation projects, doctest can sometimes feel a little awkward as a full documentation tool. doctest’s use of the interpreter session metaphor can force your example code to look strangely unlike the code you would actually write when using the library.

]]> By: Rene Dudfield http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-140914 Rene Dudfield Wed, 12 Mar 2008 04:49:33 +0000 http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-140914 doctest is pretty much designed for this type of stuff. doctests are documentation that are also a tests :) http://docs.python.org/lib/module-doctest.html cheers, doctest is pretty much designed for this type of stuff.

doctests are documentation that are also a tests :)

http://docs.python.org/lib/module-doctest.html

cheers,

]]> By: Ken Kuhlman http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-140887 Ken Kuhlman Wed, 12 Mar 2008 02:32:03 +0000 http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-140887 I haven't had a chance to actually play with it yet, but I've got Crunchy filed in this space. http://aroberge.blogspot.com/2008/01/automated-documentation-code-testing.html http://aroberge.blogspot.com/2008/02/automated-documentation-code-testing.html Of course, I've never worried myself about writing a book, and that problem probably raises a huge set of formating issues, but the Crunchy developers seem eager to tackle new challenges. FWIW, I think Johannes Woolard will be presenting about Crunchy at PyCon. I haven’t had a chance to actually play with it yet, but I’ve got Crunchy filed in this space.

http://aroberge.blogspot.com/2008/01/automated-documentation-code-testing.html
http://aroberge.blogspot.com/2008/02/automated-documentation-code-testing.html

Of course, I’ve never worried myself about writing a book, and that problem probably raises a huge set of formating issues, but the Crunchy developers seem eager to tackle new challenges.

FWIW, I think Johannes Woolard will be presenting about Crunchy at PyCon.

]]> By: Kevin Horn http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-140723 Kevin Horn Tue, 11 Mar 2008 17:22:27 +0000 http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-140723 You could build something like this around docutils, I think. It has all kinds of hooks, etc. which allow various types of processing on the text of the document. I think it should be possible to kick off a test harness of some kind using it. Or at least easily grab code from your document and test it. That said, it may not be the _best_ option, as the internals of docutils are something of a beast...and the documentation is a bit scattered. You could build something like this around docutils, I think. It has all kinds of hooks, etc. which allow various types of processing on the text of the document. I think it should be possible to kick off a test harness of some kind using it. Or at least easily grab code from your document and test it.

That said, it may not be the _best_ option, as the internals of docutils are something of a beast…and the documentation is a bit scattered.

]]> By: James Bennett http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-140464 James Bennett Tue, 11 Mar 2008 06:54:36 +0000 http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-140464 I've been fighting a bit with this myself, and haven't yet found a really good solution. For now I just keep the code open in one buffer in Emacs, the chapter I'm working on in another, and yank bits between them as needed. If you'd like to solve this problem on behalf of Python book authors everywhere, I'll buy you a beer ;) I’ve been fighting a bit with this myself, and haven’t yet found a really good solution. For now I just keep the code open in one buffer in Emacs, the chapter I’m working on in another, and yank bits between them as needed. If you’d like to solve this problem on behalf of Python book authors everywhere, I’ll buy you a beer ;)

]]> By: Catherine Devlin http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-140393 Catherine Devlin Tue, 11 Mar 2008 03:40:33 +0000 http://compoundthinking.com/blog/index.php/2008/03/11/how-to-write-a-better-book-or-just-better-docs/#comment-140393 The Red Bean Mercurial book mentions that its code samples are live and continually tested - I wonder if they'd share their test harness. http://hgbook.red-bean.com/hgbookli3.html#x4-50000.2 The Red Bean Mercurial book mentions that its code samples are live and continually tested – I wonder if they’d share their test harness.

http://hgbook.red-bean.com/hgbookli3.html#x4-50000.2

]]>