Category: book

Generating a Preview on LeanPub Using Rake

While working on the e-books I published on LeanPub, I have developed a number of useful approaches to get fast(er) feedback on how the book looks. Two earlier blog posts describe some of this:

While this provides a nice feedback cycle, sometimes I like to generate a new preview without pushing to the GitHub repository I am using to share the book content with LeanPub. This happens, when I change settings on the Leanpub site that affect the generation of the book (the title image, font faces and sizes are set via the book’s pages on LeanPub, not a configuration file in the repository).

While I could click thought the UI and navigate to the page where I can generate a new preview, I prefer using a command line tool from my local machine: Rake

The Setup

A warning: The LeanPub API documentation says: “Using the Leanpub API requires a Pro plan.

To use the LeanPub API, an API key is needed. The link to the API documentation above has information where to get that key. To easily use this API key, I store it in an environment variable LEANPUB_API_KEY.

The Rake Task Definition

In the repository of my book I have a Rakefile containing the task definitions. Here’s the one to trigger the generation of a preview on Leanpub:

require 'rest-client'

namespace :leanpub do
  LEANPUB_BASE_URL = "https://leanpub.com/<book_id_on_leanpub>"
  namespace :preview do
    desc "Generate new Preview on LeanPub"
    task :generate do |t|
      what_to_generate = t.name.split(':')[1]
      url = "#{LEANPUB_BASE_URL}/#{what_to_generate}.json"
      begin
        RestClient.post url, api_key: ENV['LEANPUB_API_KEY']
      rescue RestClient::Exception => e
        puts "Got error #{e.message} in", caller.first
        exit 1
      end
      puts "Generation of preview was triggered"
    end
  end
end

I can now easily generate a preview, without having to leave the IDE I’m using to write the book (or the command line) using this:

$ rake leanpub:preview:generate
Generation of preview was triggered

The Rakefile will likely change, for example to also support publishing a new version of the current ebook, or to make it more flexible in order to handle different ebooks.

Update (8. Jan 2021): It turns out that this is really useful: LeanPub provides a web hook to generate a _sub set_ of the book that also generates the PDF (but not the ebook and mobi file). This saves some time from pushing to GitHub to being able to review the generated file. I now use this web hook most of the time.

I now only generate for full book in all formats when I want to check that the book looks good enough to be published. Since this happens less regularly than pushing to the repository, I use the Rake task.

Writing – Advice from Johanna Rothman

Just before Christmas (2020) Jabe Bloom asked this over on Twitter::

Johanna Rothmann‘s answers were short and easy to understand (but maybe hard to actually do):

I (publicly) agreed…

…and am now signed up to be informed when the book writing class opens.

It already showing some effect: I’m (re-) starting to update “Fast Feedback Using Ruby” (for the just released Ruby 3). 🙂

Writing a (Technical) Book in an IDE

I find myself writing again more, in particular writing technical books. For this I am using a number of tools, some of which I’ve described in Writing a Ruby Related book(let) on LeanPub.

In this post I focus on the writing itself including the setup I use. When starting fresh, I use the zip file with a default content provided by LeanPub. When unzipped, the folder structure looks like this:

% tree a_potential_book
a_potential_book
├── README.md
└── manuscript
    ├── Book.txt
    ├── chapter1.txt
    ├── chapter2.txt
    ├── chapter3.txt
    └── resources
        ├── palm-trees.jpg
        └── readme.txt

2 directories, 7 files

I have used Markdown in previous books and am now using Markua (a markup format created by LeanPub). Since both are similar and many editors & IDEs identify the file type by the file name suffix, I use ‘.md’ as the suffix for the files. Also, I find renaming the files ist easier than reconfiguring editors. To do this I use rename:

% rename -g  -s .txt .md  "a_potential_book/manuscript/chapter*.txt"
% tree a_potential_book
a_potential_book
├── README.md
└── manuscript
    ├── Book.txt
    ├── chapter1.md
    ├── chapter2.md
    ├── chapter3.md
    └── resources
        ├── palm-trees.jpg
        └── readme.txt

On a Mac rename can be installed using Homebrew:

brew install rename

Now the file Book.txt needs to be updated, to also list the ‘*.md’ files:

ls *.md > Book.txt

With this set up, I import the folder into RubMine, and have a look at ‘chapter2.md’:

Example chapter 2 of the default LeanPub book
The imported default book (click to enlarge image)

Notice this line

![Palm Trees](palm-trees.jpg)

This is the Markua (and Markdown) way of to insert an image (‘palm-trees.jpg’ in this case) into the text using the cation ‘Palm Trees’. In terms of RubyMine the image file is a resource — and it would be handy to be able to open it with just a click. Here’s how to configure this in the IDE:

  1. 320Hover the mouse pointer over the folder name ‘resources’ and
  2. Open the context menu with a right click:
  3. Open the sub menu entitled ‘Mark Directory as ▸’, and click ‘Resource Root’

Now, if you CMD-click the file name in the text, the image is displayed. Nice.

For my Ruby related book, I created a sub directory within ‘resources’ named ‘code’. Any files inside that folder will now also be found by the IDE and opened, when CMD-clicked.

A Community Written Book

An Update: It‘s available on LeanPub!

The book is now available at LeanPub ➙ https://leanpub.com/softwarepeopleworkfromhome.

@MaikNog and I (@S_2K on Twitter) are preparing a community e-book, similar to Viv Richards’ (who agreed to contribute to this one. Yay!) wonderful “Around the World with 80 Software Testers“.

It’s entitled “Software People … Work From Home — Insights & Experiences From Planet Earth” and it will contain reports about life and work in these times of lockdown, personal limitation and remoteness. They are personal experiences, unfiltered authentic … and safe for work. 🙂 I would love each contribution to be easily seen as the work of a person, the human behind the words. This is intended to be a very humane collection of individual works covering one topic.

Folks have already promised to contribute material – and here’s a map marking the countries: https://drive.google.com/open?id=1riRbKTZMGdwShPZJ0f884CIbXFD2Vhli&usp=sharing

World map displaying countries with contributors to the book

If you identify as a software person and would like to contribute, we (@MaikNog and @S_2K) would like to hear (or read) from you — especially (but not exclusively!) if you’re not from one of the countries marked in that map.

All the best to you and yours — stay healthy (or a speedy recovery, should that be needed)

Update on 27th April 2020: The name changed, the map is updated and the description more precise..

Update on 10^th^ May 2020: Updated the map, now including Greece and Italy. Thank y’all!

Writing a Ruby Related book(let) on LeanPub

I wrote “Fast Feedback Using Ruby” using LeanPub. The original version was published back in 2015. Since I’m updating it to cover the most recent (at the time of this writing) Ruby 2.7 and RubyGem versions. I figured, it’s a good idea to leave a trace of my workflow and setup. 🙂

My workflow look like this:

  1. Edit Text (or image) file
  2. Save file to local disk
  3. Commit to local Git repository
  4. Push to GitHub
  5. Generate preview PDF on LeanPub using a (post push) web hook
  6. Have Leanpub automatically push files to Dropbox
  7. Have Dropbox synchronise PDF file to local folder
  8. Restart at 1
Writing workflow using LeanPub, GitHub and Dropbox

Whenever I push changes to GitHub, a new preview of the book is generated and sent to my computer. This means I get frequent and fast feedback about how the newly written text looks.

This nicely fits my working preferences and it also matches the topic of this particular book.

‚Agile Testing Condensed‘ — A Review

Agile Testing Condensed‘ is the 3rd book by Janet Gregory and Lisa Crispin. As the title already indicates, it’s a short book – the print version has about 100 pages. Luckily, I got a printed version at the Agile Testing Days 2019 in Potsdam and had it signed.

The book covers the important topics of testing in an agile context on a high level. For details it regularly refers to the other books ‘Agile Testing‘ and ‘More Agile Testing‘ (to which I contributed a section). One topic the book returns to regularly is the ‘Whole Team Approach’. I like this first of all, because to me this is the core part of agile testing. In my experience, it is this aspect that troubles teams. And second of all, I this is great, because the details described in the other books, can, at times, make it hard to see this overarching relation.

If I had to name one thing that might be improved, that would be the size of the images. To me, they came out a bit too small to be easy to read. Since I also bought the ebook (where I can zoom the images), that’s not a big deal.

I highly recommend reading ‘Agile Testing Condensed’ to everybody who is looking for an overview of the topic or who likes to have a reference at hand to quickly look up a certain aspect.

Announcement: Workshop & ebook: “Fast Feedback Using Ruby”

At the “London Tester Gathering Workshops 2015” (also see #LTGWorkshops on Twitter) I offer a workshop “Fast Feedback Loops & Fun with Ruby”. For this, I wanted to give attendees a handout, to make applying the stuff covered easier and it was planned to be a list of brief recipes.
Suffice to say that the handout grew (and it’s entirely possible that this is ‘feature creep’ in action). In fact, it grew to the point that I decided to turn it into an ebook. The book is not done yet, there’s some copy editing to do.

Fast Feedback Using Ruby

In any case: There will be an ebook, and it will be available on LeanPub at https://leanpub.com/fastfeedbackusingruby/. If you’re interested, please leave a note on the book’s pages.

%d