Authoring guide

Hi guys,

I specifically looking for advice from authors who have written books on leanpub. Basically, my question is when you are writing a 'practical guide' as opposed to a generic guide, what are the differences and good practices to look out for.

Obviously the practical guide will show real world examples, and the generic guide will just be a gist of what the thing you're writing about can do.

Any useful tips would be most appreciated including proposed book structure layout and how many pages is reasonable. What do you put in the appendix, how best to render code snippets, etc.

Thanks in advance.

Practical guide to IgnitedCMS - Book coming soon, www.ignitedcms.com

Nobody?

Practical guide to IgnitedCMS - Book coming soon, www.ignitedcms.com

Nobody?

It's not a bookwriter's forum ...

Haha thanks Narf Should I post it in the lounge?

Practical guide to IgnitedCMS - Book coming soon, www.ignitedcms.com

I'm moving it to the Lounge, don't repost (that's where this thread belongs indeed), but that's not what I meant ...

We're programmers here, not book authors. You'd be lucky if there are two or three people around who may have experience with that, and it's not reasonable to expect a quick answer.

Thanks, if there are a few around (and I know there are) that's all I'm interested in, sorry for bumping the thread.

Practical guide to IgnitedCMS - Book coming soon, www.ignitedcms.com

I think you'll find that the difference is primarily dependent on the author. Some authors will use real-world examples to illustrate "generic" concepts, while others are comfortable writing about the concepts at a higher level, using diagrams and pseudo-code to illustrate their points. I find that each style has its strong points, as the lack of cut & paste code examples in the latter forces me to understand the concepts better before attempting an implementation, while the former approach could get me through a tight spot in a pinch, while allowing better understanding to come along with time and further use.

Since I wasn't directly involved with most of the things you're looking for on the books I've worked on to date, I can't really help much. Leanpub takes care of a lot of the details for you on formatting/rendering the text/code (read their manual/guide before getting too far into the process, if you haven't already). The most important thing related to that is to come up with some rules to follow (and check, and double-check) to ensure that your book is consistent. For example, determine from the start what coding style guidelines you'll use in your code snippets and, if possible, configure your editor to enforce that style. You should probably also consider how formal the text will be, and which pronouns you'll use.

Bonfire

Practical CodeIgniter 3
CodeIgniter Testing Guide

Excellent, thank you mwhitey, I never new leanpub had a manual, is it customary to use code syntax highlighting when displaying code snippets and line numbers?

How do you achieve this, do you simply screenshot your editor or do you typeset all the line numbers and code again. I'm using indesign to create my pdf, which definitely helps keep a consistent style throughout.

Practical guide to IgnitedCMS - Book coming soon, www.ignitedcms.com

In addition to reading the manual, I would recommend setting up an author account on Leanpub and checking it out before you get too far along. The books I am working on with Lonnie and Kenji are written in Markdown, with a mix of inline code snippets and imports from PHP files. For me, it's only slightly different from working on Bonfire's documentation or writing a comment on GitHub, and being able to do something like this to add a code snippet is pretty sweet:

Code:

{line-numbers=on,crop-start-line=10,crop-end-line=25}
<<[Title Of Code Snippet](code/MY_Controller.php)

Very few people would want to see code as it's displayed in my editor, and it isn't optimal for print, either. Additionally, an image of text doesn't work well when you need to make it available in multiple paper sizes or on mobile devices (it would also be difficult to make an image accessible to users with vision problems).

Bonfire

Practical CodeIgniter 3
CodeIgniter Testing Guide

Thank you so much that has answered most of my questions. It looks like a very similar syntax to LaTex so I better ditch my pdf generated in indesign.

Practical guide to IgnitedCMS - Book coming soon, www.ignitedcms.com