Just Enough: Co-Authoring in Leanpub

Leanpub is an writing platform that allows authors to develop and publish books that are ‘living’ in the sense that they can exist in a constant state of change and are suited to being published in a serial format (being constantly added to).

Getting Started as a Co-Author

Create a Leanpub Account

As a co-author you will need to have a Leanpub account already.

There are instructions here but the first step is to go to Leanpub’s homepage at leanpub.com and click ‘Sign Up’ at the top right of the page. This takes you to the ‘Create Account’ page.

During the sign up process you are welcome to create a pseudonym instead of using your real name although you can change your ‘pen name’ on a book by book basis so that allows you to provide a degree of anonymity when co-authoring if you wish.

Create a Dropbox account

This will only be required if the book is being written using the Leanpub’s shared Dropbox method. This is the current default method, but a Github based environment for the book may be preferred as this may provide better version control.

Getting Invited to Co-Author

Whomever is the author will add you via your username that you selected when you signed up. You will be emailed an invite to co-author and you can accept on the Leanpub dashboard.

As a co-author you will receive a percentage of any royalties that the book makes. The percentage is set when the author sends the invitation. Unfortunately it is fixed at this value and if it needs to be changed (more co-authors added for instance) then the co-authors need to be removed, the percentages changed and then re-invited again. That is a bit of a phaff-about but so long as there’s not a lot of coming and going of co-authors, it’s survivable.

If the book being written is being done so via a shared drop-box account then the folder where the files reside will need to be shared manually by the author.

Being a Good Co-Author

Working as a group towards a goal that requires a degree of close cooperation it behoves us all to remember that we need to behave and play nice. Or in the words of Wheaton’s Law : ‘Don’t be a dick’.

Everybody Writes

If you volunteer to contribute as a co-author, you need to write something. That doesn’t mean edit other peoples contributions. It doesn’t mean add a couple of paragraphs here and there. It means to add a substantial body of text that you can rightfully stand back and say “I have contributed in a meaningful way”.

Don’t be simultaneously editing half a dozen different areas at the same time. Work on one or maybe two things (if necessary) at a time so that you don’t prevent someone else from stepping in to add content to an area. If you have a good reason for ‘putting dibbs’ on a topic, make sure that the reason is appropriately communicated and justified to the group.

Remember that adding content adds value.

Respect Others Work

People will want to work on a book for various reasons. They will want to make a difference, to add something meaningful to the collective effort or maybe they just enjoy the process of writing stuff down. Whatever the reason, it may rub people the wrong way if you go and edit their contributions without being polite and talking to them first. Not everyone’s grammar is perfect. Spelling may not be their forte or they might have gotten something flat out wrong, but whatever the reason, it makes for a more harmonious environment if we check in with each other if we feel like someone’s work needs some polish.

This goes both ways of course. No-one should expect that their work is above scrutiny and we need to remain focussed on the ultimate result which is producing a body of work that meets its goal and has value (See humility).

Humility is Important

Each of us should realise that we are imperfect. Ask for help in proof-reading. Don’t be offended if mistakes are gently pointed out. Recognise that others will see things that we won’t and sometimes we still won’t see it even after they’ve explained it a couple of times, so be patient.

The Purpose of the Book is Your Guide

Each book will have a purpose. If the purpose of the book is to provide minute detail of a complex subject, it’s not appropriate to to spell out the simple stuff that the reader will find distracting or a waste of their time. By the same token, if you’re writing a beginners guide, don’t get bogged down in the minutiae.

The Responsibilities of Being the Primary Author

If you’ are the original author of the book, you have a few extra responsibilities that you will need to address. You will be responsible for inviting and managing any co-authors. This is a job that will need some juggling as co-authors come and go. Be proactive about it.

You will drive the purpose and ‘feel’ of the book. Make sure that it stays on track. Communicate actively as people make additions and changes. Ensure that editing conflicts (people trying to write the same piece at the same time) doesn’t happen and when it does, get it sorted out. You will be the person who should care about the book the most. Ultimately you should be expecting to carry the burden on your own, but should be grateful if other co-authors offer to assist. You will probably be the logical person to act as editor of the book. Make this clear if it isn’t you and if it is, be true to the books purpose.

Editing

Every book needs an editor. That means a single editor who makes sure that the content has the appearance of being a seamless, coherent body of work. Often this would be the primary author but it could be any nominated member of the team. Whatever the case, their role should be clearly articulated to the team and they should ensure that they keep the book true to its purpose.

Don’t be offended if the editor wants to make suggestions about some of your content. Expect it. They will ultimately need to work through the entire book and massage the content into a form so that it appears to have come from a single writer. This is their job. They will talks to all the co-authors to make sure that they know what is going on, but they need to make sure that the responsibility of being the editors for a book is taken seriously.

Guidance

Make sure that the purpose of the book is known clearly to all the co-authors. This is a vital tool in assuring that the end result is successful and can stand up as a quality work.

Administration

Be proactive about getting co-authors on board and managing their connections and contributions.

How to Add Content

Being an author is all about adding content and value to a written work. Leanpub have a number of ways that this can be accomplished. This varies from the file management that is used and the way that the book is structured to the method of formatting.

When working as a co-author it’s also worth making sure that you can add that content in a way that doesn’t conflict with any other work being written by other co-authors.

The Book.txt File

The content of a book is tied together by the Book.txt file (which is in the ‘manuscript’ folder in the Dropbox folder for the book). This is a list of all the files you want in the book, in the correct order. It’s a good idea to think of it as a table of contents where each file is a chapter.

The list of files in Book.txt does not have to include all of the files in the manuscript folder. When Leanpub creates a Preview or a published version of the book, it only uses the files listed in Book.txt, not all the files in your manuscript folder. That way, if a chapter is not ready, you can keep working on it in the manuscript folder, but just leave it out of the list in Book.txt until you think it’s ready. Alternatively you can place a hash mark (‘#’) at the front of the line of the chapter you’re writing and it won’t be included in the book when it’s published.

For example the following could be the contents of the Book.txt file. In this example the files are logically broken down by topic into convenient chapter blocks. Some chapters aren’t ready for publishing and are prefixed by ‘#’ marks. These ‘#’ marks should not be confused for the ‘Header’ prefixes used for Markdown in the book itself. In the Book.txt file they are a simple mechanism for rem-ing out a line.

introduction.txt

cheat_sheet.txt

First_Chapter.txt

Second_Chapter.txt

Third_Chapter.txt
Section_1.txt
# Section_2.txt
# Section_3.txt
# Section_4.txt
Section_5.txt
# Section_6.txt

Avoiding Conflict

Sometimes it can be difficult to know who is working on what file. It could be useful to add in a rem-ed out line in the Book.txt file to let people know who is working on what topic. Something like the example below will work;

Third_Chapter.txt
Section_1.txt
# Section_2.txt
# Section_3.txt
# Sam currently working on section_4.txt and will un-comment when complete
# Section_4.txt
Section_5.txt
# Section_6.txt

Markdown

Markdown is the formatting method used for the content of the book so that it can ultimately be published in a range of formats (pdf, epub. mobi, and html).

For information on the various formatting options in markdown, and especially the Leanpub interpretation, check out the Leanpub manual. Some of the basics follow…

Headers

These prefixes allow headings that align with the concepts of chapters (#), sections (##) subsections (###) etc;

# H1 Chapter
## H2 Section
### H3 Sub-Section
#### H4 Sub-Sub-Section

This would appear as follows;

Paragraphs

Just type in an ordinary block of text. To separate paragraphs, put a blank line between them.

Bold

If we enclose text within sets of two asterisks (**bold text here**) we can generate bold text. Therefore …

This is **bold**.

.. becomes this …

This is bold.

Italics (Emphasis)

Enclose text within sets of single asterisks (*italicised text here*) to make text italicised.

This is *italicised*.

.. becomes this …

This is italicised.

Links

Create links to external sources by wrapping square brackets around the link text and round brackets around the URL as follows;

[Leanpub](https://leanpub.com/)

… becomes…

Leanpub

There are also crosslinks that can link to different parts of the document. See here for details.

Images

Images used in the book are normally stored in the ‘images’ directory that is in the ‘manuscript’ directory. To include them in the book include a link similar to the following where ‘The image caption’ is the caption that you want to have appear under the picture and ‘coolimage.png’ is the name of the image file that is in the ‘images’ folder.

![The image caption](images/coolimage.png)

The default method for inserting an image is to do so as a centred picture that scales to fit the width of the page. There is obviously a limit to the useful resolution that we can include in a book, so anything over 300 PPI (Pixels Per Inch) is a waste of file size. Leanpub have a useful guide to image size here, although if you want to scale your image on the page to less than the page width you can add a scaling factor immediately preceding the image link like so;

{width=60%}
![The image caption](images/coolimage.png)

Blockquotes

A blockquote is an indented block of text that appears as an ‘aside’. They can be formatted this way for several different reasons and there are a few different ways to designate the text to make them appear in different contexts in the text.

A blockquote should have the line start with an angle bracket (>). Every additional line with the angle bracket adds more content to the blockquote. For example the following;

> This is the start of a blockquote
>
> This is the continuation of the blockquote and it can keep going on from
> here for as long as we keep including the angle brackets at the start of
> the lines.

… will produce this …

This is the start of a blockquote

This is the continuation of the blockquote and it can keep going on from here for as long as we keep including the angle brackets at the start of the lines

We can nest blockquotes and add headers and lists and all sorts of stuff. When you find the need to get fancy, check this link out.

To make block quotes have additional context they can be prefixed with a character which generates a block with a bit of a difference.

For instance a A> creates an aside (or ‘sidebar’) which can be highlighted or surrounded with a line.

There are also the following character prefixes to show variations that include icons to provide context;

• W> For Warnings
• T> For Tips
• E> For Errors
• I> For Information
• Q> For Questions
• D> For Discussions
• E> For Exercises

We can even add a custom blockquote from the ‘Font Awesome’ list using a Generic (G>) tag.

Lists (numbers and bullets)

To create a numbered list start each line with a number and a period (1. ) with a space after it. Don’t put a space in between each line and the list will auto generate. For example;

1. This is the first line
1. This is the second line
1. This is the third line

… will become …

1. This is the first line
2. This is the second line
3. This is the third line

To create a bulleted list place a hyphon (-) and a space at the start of each line. Don’t put a space in between each line and the bulleted list will auto generate. For example;

- This is the bullet point
- This is the second bullet point
- This is the third bullet point

… will become …

• This is the bullet point
• This is the second bullet point
• This is the third bullet point

There are several fancier ways to nest lists which should be checked out here.

Code blocks

If you want to insert a block of code into the book, you can insert it with a set of 8 tildes above and below the block which will cause the code to appear as if it is code from a terminal (standard spacing and ‘Courier’ style).

So something like the following (which, when written down appears to be a list of separate lines);

var margin = {top: 20, right: 20, bottom: 30, left: 50}, width = 960 - margin.left - margin.right, height = 500 - margin.top - margin.bottom; var parseDate = d3.time.format(“%Y%m%d”).parse;

… becomes …

var margin = {top: 20, right: 20, bottom: 30, left: 50},
    width = 960 - margin.left - margin.right,
    height = 500 - margin.top - margin.bottom;
var parseDate = d3.time.format("%Y%m%d").parse; 

And because the code above will normally appear to be standard text, we can override the default settings for the block and force it to syntax highlight the code to make it easier to read. We can do this by adding a line above the code that designates the language that we’re using (for example {lang="js"}).

Which means that;

var margin = {top: 20, right: 20, bottom: 30, left: 50},
    width = 960 - margin.left - margin.right,
    height = 500 - margin.top - margin.bottom;
var parseDate = d3.time.format("%Y%m%d").parse; 

… becomes …

var margin = {top: 20, right: 20, bottom: 30, left: 50},
    width = 960 - margin.left - margin.right,
    height = 500 - margin.top - margin.bottom;
var parseDate = d3.time.format("%Y%m%d").parse; 

There is a range of supported languages including;

• JavaScript (js)
• Python (python)
• Java (java)
• Bash (bash)
• JSON (json)
• SQL (sql)
• HTML (html)
• PHP (php)

And if you just want plan text, you can use {lang="text"}.

A default starting point for a code block would be as follows;

{lang="code-language"}
/~~~~~~~~
code here 
/~~~~~~~~

Escaping characters and Excluding lines a book

If you want to escape a character that is part of the Markdown syntax and prevent it from formatting the text, just but the backslash (‘/’) character in front of it.

If you want to include a line in your text, but prevent it from appearing in the book, add two ‘%’ characters at the start of the line.

%% This line will not appear in the book (kind of like a comment). 

Pagebreaks

To get a page break to occur at a particular point insert the following line in the text (with a blank line above and below) and this will automagically happen.

{pagebreak}

Values of Co-Authorship

The following is a loose set of values that should be considered when participating in a group working on a book. I’m sure it’s not exclusive or complete, but at least it’s a start.

1. Don’t be a dick
2. Everybody writes.
3. Respect your co-authors.
4. Be humble.
5. Let the purpose of the book be your guide.
6. Take responsibility.