small medium large xlarge

28 Oct 2010, 18:38
Wes Shaddix (2 posts)

I’ve had an idea for a book for a long time but have always been hesitant to start it because I don’t know the best tools and format to use. I really like the django book online because it allows readers/reviewers to comment inline. I also would want to use a format that could then be easy to publish both in print and the major electronic formats (pdf, ebook, mobi, kindle).

Does anyone have any advice or suggestions on which software, web apps, formats, etc. to use?



28 Oct 2010, 19:34
David Copeland (512 posts)

You could use Markdown; it doesn’t add a lot of noise to your text, and can be easily translated into HTML. From there, you could transform it to any reasonable format for publishing pretty easily…

28 Oct 2010, 22:03
Stu George (6 posts)

I’d write in all plain text and texify it last. the idea is not to waste time on marking it up as you go and fiddling around prettying it up.

write first. markup second.

29 Oct 2010, 12:16
Shawn Boyette (1 post)

^^^ This.

I’m not terribly good at the writing process, but one thing I have learned is to concentrate on the words first and the formatting last. Anytime I start fiddling with markup while writing, it becomes a trap where I stop writing and start obsessing about document organization and markup.

Closely related (for me) is trying to edit while writing, which is at least as bad. Just make the words come out. They will be imperfect, but writing now and then re-reading (and re-reading) later will get more words on the page and result in better text with less pain. Editing at write time is asking yourself to pre-edit things you haven’t written down yet. Give yourself editorial distance and you’ll be able to see what’s good, what came out muddled, things that should be next to each other, and so on.

30 Oct 2010, 17:57
DR I M PIPER (1 post)

Can I put in a vote for structure? I wrote a book last year and found it really useful to start by thinking about the book structure overall. It doesn’t need to be a complete structure, but starting with an outline of the principal ideas that the book is going to cover does no harm at all. A big advantage of this top-down approach is that it provides you with some convenient buckets in which to pour your ideas as you have them. This works well for me as I don’t think in a particularly linear way, and often found while working on one chapter that I had an idea of something to add to a completely different part of the book.

Structure and formatting are often confused, not least because of word processing systems like Word. There is nothing wrong with considering how a chapter will break down into sections and subsections, and you ought to be able to do this without assigning fonts and indentation and so on.

Incidentally, regarding tools, I have to include a plug for Scrivener. This is a Mac program (though wow, I see that the Windows version is currently available in beta - that is designed specifically for writers. I suppose one of the things I like most about it is that it allows me to work in the kind of structured way described above, but still has a lot of flexibility in how you write. It also gets out of the way when you want it to with a full screen mode, letting you focus on the words without a lot of page furniture to distract you.

30 Oct 2010, 19:58
M. Edward (Ed) Borasky (8 posts)

I use Linux and have a complete LaTeX environment, plus LyX and TeXmacs. I’m planning to use LyX to do the writing - I pretty much have the workflow down and there are modules for “literate programming” in Python and R.

31 Oct 2010, 15:47
André Roberge (1 post)

I’m using a simple text file with reStructuredText syntax and convert it to pdf using rst2pdf. It’s easy to include source code from files that are kept separate … and bug free. :-)

01 Nov 2010, 02:35
Bob Cochran (170 posts)

I would just use OpenOffice Writer. The idea is to write. You can prettify later.

01 Nov 2010, 06:29
M. Edward (Ed) Borasky (8 posts)

I absolutely positively will not use OpenOffice Writer. It’s a feeble attempt at compatibility with Microsoft Office that destroys the documents it touches. If I need to work with Microsoft Office documents, I’ve got Office 2007. But LyX is so much better for code, figures, tables and math that even Office isn’t usable.

01 Nov 2010, 14:10
Raymond Yee (47 posts)

I agree with Stu that the focus this month should be on writing text and not focusing too much on formatting. However, if you have a good set of tools to format the text without distracting yourself from writing, that’s even better.

I will take a look at LyX though I’m hoping to find a toolset that allows for good production of DocBook output and integration with a bibliographic data manager (such as Zotero).

01 Nov 2010, 15:47
Diego Zamboni (70 posts)

I have started to write some content for the book I have in mind, and which I am determined to put in better shape during PragProWriMo. I had started writing in LaTeX, but I find myself getting bogged down in details (“I wonder if there’s a package for doing X?”, “how should I format this?”, etc.) During this month I plan to use to write plain text (maybe use Markdown) to keep content flowing without worrying too much about formatting. I have signed up to the 750words November challenge, so if I don’t keep up, my name will go up on the Shame Wall. Motivation is key :)

01 Nov 2010, 17:20
Josh Carter (40 posts)

I used Markdown for PragProWriMo 2009 and posted on my web site as I went along. I can’t recommend Markdown enough for simply getting stuff down with minimal fuss. LaTeX, either with LyX or a plain text editor, is great if you need more structure. However, don’t get so bogged down in structure that you don’t write!

I suggest for code samples that you keep those separate and fully unit test each one; treat the source file as the authoritative version if you need to copy-n-paste the sample into your written text. (For “real” publishing it’s preferable to have a system that can slurp code excerpts straight from source files, thus avoiding a source of manual labor and error. Don’t worry about this for November, though.)

02 Nov 2010, 00:42
Travis Swicegood (117 posts)

If you know Markdown, use that. If you know ReST, use that. If you know LaTeX, use that. Use whatever you’re comfortable with. Trying to figure out a new markup just to write is going to add another layer on top of it. Remember, small changes. This month is all about the change of building a habit of writing every day.

Me personally: I’m using Sphinx and ReST for the text. I know the tools (they’re my default for project documentation) and it’s dead simple.


You must be logged in to comment