An Ordinary Developer's Journey to Authorship

I recently wrote a book called Finishing VueJS Over a Cup of Coffee. Since writing long texts like books was actually my first time, I started writing completely ignorant about the book writing process or publication process, so there were quite many twists and turns along the way.

So in this post, for those who want to write books like me, I want to talk about the writing process and difficulties from August 2018 to July 2019.

How Did I End Up Writing a Book?

First, the reason for writing the book was receiving a proposal from my friend developer Kim Younghoon to co-author a book together. Actually besides college general education reports, a few blog posts, and company technical documentation, I’d never written anything. Even looking at this blog’s post archive now, you can see at a glance that before June 2019 when I seriously got into blogging, I wasn’t pouring out posts once or twice weekly like now but just writing occasionally when I felt like it.

Plus when first receiving that friend’s proposal, I hesitated a bit for two reasons about whether to write it - the first reason was “am I skilled enough to write a book?” And the second reason was a bit fatal…

Actually I’m someone who never read tech books since college textbooks.

Making another book-coming-out...

I like reading, but regarding studying I’m the “isn’t the internet more convenient?” type, so rather than tech books I mainly read novels or essays, books unrelated to technology like organizational culture or philosophy.

Plus, those who’ve read my posts a few times might know, but my study style isn’t reading books one by one from basics. First I decide what to make, then find and absorb necessary information each time, use it immediately and move on. (Of course that’s why my knowledge is wide but shallow.)

My reading taste is closer to this side. (Seems like one spy snuck in but let's ignore it.)

So why did I write a book? Well, there are various reasons but narrowing down to a few, roughly this:

1. I want to make tangible work that I can hold and see, not intangible work like code.
2. While writing a book, couldn’t I organize knowledge I vaguely know?
3. More people than expected were starting to learn coding through books.

When I said I’m writing a book, some people occasionally cracked jokes like “Wow, Evan! Now you’ll make money from books too?” but I didn’t expect much because I thought from the start that money you can make selling books isn’t that much.

Rather, for me the book’s appeal was less about side income and more about my own satisfaction of having written a book and being able to share what I know with others.

It’s the same with this blog - honestly how much would I make from this blog? From the start my posts aren’t content the general public can consume. So even if the blog really takes off, making at most 1 million won per month would be a lot.

Of course 1 million won isn’t small money, but it’s not life-changing money either so I think it’s meaningless. So I’m just running the blog wanting to share my thoughts and knowledge with others.

Wanting to Make Tangible Work

Being a developer, I make programs daily. But programs feel more abstract than like real existing objects. Like intangible conceptual things you can’t touch with hands or smell.

But when I think of books, the image that immediately comes up is a synesthetic image with various senses together - paper smell when opening new books, texture felt when taking books from bookshelves, sounds heard when turning pages one by one - so it felt very different from making programs. That the output comes as shaped objects rather than mechanical something felt very new.

And crucially, I’m a Kyobo Bookstore fanboy who went to Gwanghwamun Kyobo Bookstore extremely often holding Grandpa’s hand since age 5. Imagining my book displayed at Gwanghwamun Kyobo Bookstore with such memories felt somehow touching and strange.

Organizing My Knowledge While Writing

Though I wrote a book about Vue, I obviously didn’t start writing knowing everything about Vue perfectly. Of course having 2 years’ experience using Vue makes me familiar, but being familiar doesn’t lead to being good.

So I re-studied Vue from basics thinking I’m studying it again, re-reading from official docs. Looking closely, this is similar to blog posting - for example, if writing about Vue’s lifecycle, naturally most people research. Because I can’t be sure what I know is correct. In this sense, the burden felt from unspecified people reading my writing seems similar whether books or blogs.

Plus, I actually never separately studied Vue. I just joined a company and that company had already adopted Vue, so I started using Vue, and after that I just looked up what I needed while developing business. (So components I wrote early after joining are complete disasters.)

For such reasons, I thought “since it came to this, let’s properly solidify my VueJS knowledge.”

More People Than Expected Were Starting Coding Through Books

As mentioned earlier, I’m someone who thinks “studying is more convenient with internet than books!” so I was skeptical about tech books. So when my friend first proposed co-authoring, writing the book itself felt somewhat meaningless and I said “who studies from books these days? Everyone searches on internet,” but that friend’s response was exactly this:

Dude, for people studying for the first time, it might even be hard to know what keywords to search for on the internet.

Hearing this, I immediately realized my thinking was quite short. Somewhere I read “humans unconsciously try to project themselves onto others,” and that was exactly me.

Because I was always comfortable studying from internet, I naturally thought others would be too, but I forgot that basically studying from internet requires the premise of knowing what keywords to Google to get the information I want.

Naturally, people first encountering development or unfamiliar with Googling can feel entry barriers in this regard, but I wasn’t thinking about that. So hearing that friend’s words, I thought:

It might be better to build capability to Google alone after studying through books with relatively lower entry barriers.

Of course, obviously reading one book won’t suddenly make someone an absolute Vue master, but at least after reading the book and understanding overall content, I wanted to help readers gain ability to find keywords alone and Google and study more about what they want to know more.

Besides these, there were other reasons like writing one more line on resumes or “being an author is kinda cool…?” plus altruistic reasons like “contributing a bit to developers’ ecosystem,” but the representative reasons greatly affecting my motivation were those three above. Ultimately after pondering, in late August 2018, I took my friend’s hand and entered the difficult path.

Before Writing the Book

After co-authoring with my friend was decided, we first had a brief meeting with a publishing company employee at a cafe near Yeoksam Station. The content was roughly simple things like send us a writing plan, how royalties come out, how contracts will proceed.

Until then my friend and I had only talked roughly about “we should write this and that content,” but now we had to discuss details to write the writing plan to send the publishing company. The key point among several things agreed then was “when readers finish this book, they should at least be able to develop applications when joining companies.”

This came after reading several other Vue books currently on the market. Books being sold mainly explained APIs or technology principles focusing on that technology, and examples also tended to make simple To Do lists or small applications with similar architectures.

The disappointing point my friend and I felt reading such books was “after reading this, can you work if immediately deployed to actual work?”

No matter how much you learned through books what Vue APIs exist, what order lifecycle executes in, problems new developers face after joining companies aren’t simple problems like “which lifecycle should I put this logic in?” but higher-level problems like “what units should I divide components into?”, “Should API communication logic be in components? Or in Vuex store?”, “How should I manage logged-in user state?”

So I thought it would be success just making readers think “Huh, I tried something similar to this once?” when encountering those problems at companies after writing this book’s examples once, and my friend thought identically, so deciding the book’s big direction wasn’t difficult.

Scene reminding me of some meme seen somewhere

After the book’s big direction was decided, my friend and I definitely met once or twice weekly after work, went to nearby cafes, and started writing the writing plan together. The writing plan includes roughly this information:

1. Title (tentative)
2. Author
3. Writing date
4. Book’s core concept
5. Content summary and features
6. Trends of technology related to this book
7. Expected completion date

There are more pieces of information but the big framework is roughly this. Since the writing plan written then is also material the publishing company uses when promoting the book later, it’s good to write as detailed as possible.

Anyway, after writing and submitting the writing plan as the publishing company requested, we started full-scale writing.

Let’s Write Like Developers!

At first we started writing using Google Docs. Google Docs provides font style features like H1, H2, so we could write documents setting styles agreed beforehand. But when we wrote about 3 chapters with Google Docs, I started thinking Google Docs was quite unproductive.

When changing fonts or attaching images, having to position the cursor at the part to change then click menus with mouse felt too cumbersome, and concentration flow broke each time. Plus, having to set font styles to publishing company standards every time creating new documents for each chapter also lowered productivity.

And my friend and I reviewed parts each other wrote by leaving comments on Google Docs documents to catch missed parts or unify writing style. However I thought this method was a bit unproductive - from the reviewer’s perspective it was hard to know what content was added this time, what content was deleted, and from the review receiver’s perspective it was hard to see at a glance where in the document comments were left.

So I started pondering “how can I focus only on writing without spending time on actions other than writing?”

Writing Books Using Markdown

What I chose as a result of my pondering was the Markdown format. Since both my friend and I are developers, first Markdown format was a very familiar format to us, and the document’s overall style was already decided, so it seemed I could keep focusing only on writing without worrying about style or doing separate work.

But since publishing companies manage manuscripts using MS Word, ultimately when sending manuscripts to publishing companies we had to send docx files, and when receiving book reviews from other reviewers we had to send pdf files. So I had to find ways to convert Markdown files to docx or pdf files.

So I found libraries called pandoc and markdown-pdf. pandoc supports converting various format documents enough to advertise on its homepage as Universal Document Converter. Of course it also supports converting Markdown to docx. But since it doesn’t support converting Markdown to pdf, I had to find other libraries to implement that feature, during which I found the markdown-pdf library.

After finishing research up to here, I proposed to my friend to switch from Google Docs to Markdown, and my friend accepted after pondering, so after that all book writing proceeded using Markdown and Git.

Version Managing Documents Using Git

Another problem when using Google Docs was difficulty managing document versions. Of course Google Docs also lets you check content added or deleted in each version by entering the File > Version history menu, but the disadvantage is the version isn’t clearly what units they’re grouped by.

But using Git, when committing you can divide into meaningful units and write accurate commit messages to inform the other person exactly which parts of the document were modified. Also, after writing certain units of documents, you can have the other person review through Pull Requests, ensuring at least one review of parts each wrote.

So my friend and I created a repository on Github and proceeded with writing taking one chapter at a time, but agreed to always send Pull Requests and merge when wanting to merge content to master branch, and as a result we could proceed with writing without great difficulty understanding content even if not parts each wrote.

Benefits of reviewing.jpg

Of course, when doing full reviews later there were many parts to fix at once so we struggled a bit with Merge Conflicts, but if we’d proceeded with Google Docs, there was high possibility of passing without knowing where two people simultaneously modified.

Converting Documents

Documents written like this were partially published converted to PDF at intervals. As I’ll explain below, early in writing my friend proposed the idea “let’s recruit our book’s target reader demographic and run a study with our book.” So we were running studies every Saturday using the written book as reference material, so we continuously had to convert md files to pdf.

So I wrote a simple publication script using the markdown-pdf library and continuously partially published when finishing writing each chapter so study participants could progress without interruption.

// vuejs-book/scripts/publish.js
glob('book/**/*.md', null, (err, mdFiles) => {
  const pdfFilePaths = mdFiles.map(path => {
    console.log(`Ready ${path}`);
    const newPath = path
      .replace('book/', `${destDir}/`)
      .replace('.md', '.pdf');
    return newPath;
  });


  mdpdf({
    preProcessHtml: preProcessHtml(basePath),
    cssPath: './custom.css',
    remarkable: {
      html: true,
    }
  }).from(mdFiles).to(pdfFilePaths, () => {
    pdfFilePaths.forEach(pdf => {
      console.log(`Created ${pdf}`);
    });
  });
});

preProcessHtml is a function written because after proceeding with conversion, image paths in the book didn’t match so images didn’t display in pdf files - it plays the role of first parsing Markdown to HTML, finding img elements, and changing them to links using the file:// protocol. After going through this process and converting HTML to pdf, images attached normally.

We uploaded pdf files published like this to Google Drive so study members or reviewers could immediately check partially published content. And we converted docx files to send publishing companies using pandoc.

// vuejs-book/scripts/deploy.js
glob('book/**/*.md', null, (err, mdFiles) => {
  mdFiles.forEach(path => {
    const chapter = path.split('/')[1];
    console.log(`Ready for ${chapter}`);

    const newPath = path
      .replace('book/', `${destDir}/`)
      .replace(`${chapter}/README.md`, `${chapter}.docx`);
    const args = `-f markdown -t docx -o ${newPath}`;
    const originSource = fs.readFileSync(`${path}`, 'utf-8');
    const source = originSource.replace(/\(\/assets/g, `(${basePath}/assets`);

    nodePandoc(source, args, (err) => {
      if (err) {
        console.error(err);
      }
      else {
        console.log(`Finish ${chapter}`);
      }
    });
  });
});

Document conversion scripts written like this were registered as npm scripts so we could conveniently extract md format to pdf and docx formats anytime.

// package.json
{
  "scripts": {
    "publish": "node scripts/publish.js",
    "deploy": "node scripts/deploy.js"
  }
}

Actually at first when just converting md format to pdf there were no problems, but later when converting to docx format through pandoc, issues related to font styles occurred.

When converting to docx format using pandoc, you can set what’s called a reference document - if you set custom font styles in this document, it makes converted documents using the same font styles referring to this document’s font styles.

So at first just trusting this feature I thought “I just need to make one reference document with font styles set according to publishing company format,” but when actually running scripts using the reference document option, code block styles attached to documents went haywire.

So ultimately when finally sending manuscripts to the publishing company, I used the method of converting md format to docx format’s default font styles using pandoc, then manually changing that document’s font styles by hand.

Well, I struggled quite a bit at the end, but still by choosing md format I could save lots of time during the writing process, plus I could version manage using Git, so overall I think it was a good choice.

Conflicts During Co-authoring

Since I didn’t write the book alone but co-authored with my friend, communication to align opinions and draw consensus was also one very important task.

Actually my friend and I had experience proceeding with side projects together and usually got along quite well, so we’re close friends who even went on overseas trips together. But due to book media characteristics where unlike code it’s impossible to modify after deployment, the desire to “finish as perfectly as possible” made aligning opinions more difficult than usual.

Different Perspectives on Design

What caused many opinion conflicts initially was example application design. Since examples going into books are information exposed to unspecified people, they should be written using widely applicable knowledge excluding subjectivity as much as possible. So my friend and I talked tremendously about “how should we take example application design?”

Simply from component naming and project directory structure to deep topics like which component should Dispatch actions for store state changes - we talked about various things. Ultimately only after drawing consensus through such endless communication could we enter example application development.

We decided everything from Form component definition to what libraries to use.

Different Working Styles

Second was working styles. Actually this was a really unexpected part - I already had experience proceeding with side projects with this friend, and even during opinion conflicts we came to very mutually satisfying conclusions proceeding, so I thought this time would be the same. But whether because this was paid work or had deadlines, situations very different from side projects unfolded.

First, I’m not the style chased by deadlines doing any work. I can do this because I minimize variables arising during work and completely block work that seems risky. And crucially my personality is somewhat relaxed. To put it nicely relaxed, badly lazy - well anyway that kind of personality.

But this friend has incredible passion whatever they do. Whether work they don’t want to do or want to do, always doing their best. I think this friend can do this because basically they have a personality with great sense of responsibility. (Well might not be. Even friends have unknown parts)

Exactly these parts about this friend greatly stimulate me, and even thinking developer to developer excluding the friend part, I think they’re a very good developer.

But doing work with deadlines together, from this friend’s perspective it seemed I wasn’t actively participating, and I had thoughts like “this isn’t work to stress this much about…” And being human, as deadlines approached we inevitably felt anxiety like “what if we can’t keep promises with the publishing company,” and both working at companies had to do company work separately. So I think physical and mental fatigue accumulated.

Still fortunately, the biggest commonality between this friend and me was knowing the importance of soft skills like communication. So even stressed chased by deadlines, we could finish writing without major conflict by maximally considering each other and listening and exchanging opinions.

Reviewing the Book

While writing the book my friend and I kept reviewing using Pull Requests, but reviews from author perspectives are mainly mechanical reviews like typo correction, writing style unification, while reviews from other reviewers are qualitative reviews hard to notice from author’s perspective like “is this content really helpful?”, “would be better with this content.” So we wanted to collect as much feedback as possible from reviewers during or after writing.

Actually I don’t have many developer connections and don’t like meeting people, so I didn’t have many people to ask reviews besides workplace colleagues. But my friend had richer connections and better social skills than me, so had many people to ask reviews. (Amazing…) For such reasons, book reviews were work I couldn’t do alone and really thanks to my friend. And I also started thinking “ah should I network too…?” based on this experience.

Study Members’ Reviews

As explained above, when first writing the book my friend who knew such review importance first proposed the idea to recruit our book’s target reader demographic and run a study with our book, and though I hesitated at first, I was persuaded by words that reviews from other reviewers are important so we proceeded with the study.

I’m shy so I’m not used to studying with first-time people. So at first I pondered tremendously about “what should I do for study members…?” but once the study started I knew such worry was my groundless fear.

All study applicants passionately asked questions first and clearly expressed opinions about parts wanting to know more, so I could proceed with the study comfortably. And everyone had good personalities so even shy me could fit in well.

While writing the book, receiving feedback from study members who were actual target readers and modifying the book somehow gave me confidence about the book, and seeing them learn smoothly studying with the book I wrote, I felt somewhat proud.

Actually I didn’t have desire to proactively share knowledge with others first, but writing books this time and running studies, seeing knowledge I thought was nothing much greatly helping others, I became a bit interested in education and my shyness improved a bit. (Still the path to social butterfly is long and tough…)

Working Developers’ Reviews

After finishing writing the book, I also asked surrounding working developers for reviews - such people are called beta readers apparently. I first learned this time.

Beta readers proceeded divided into full reviews and chapter reviews according to their free time, and they gave really meticulous feedback like revisiting parts I missed while writing and pointing out explanations that might be hard to understand, so it was very reassuring.

Wrapping Up

Actually at first I started with the complacent mind “book? Just feels like a slightly long post,” but soon realized that wasn’t it. Though not written in this post, making example applications was also no joke - the problem was when modifying example applications, I had to find the same parts in the book and modify code blocks and change code explanations accordingly. (Plus had to make 2 client applications and API server.)

Even if example applications and book content synced slightly off, readers could feel considerable confusion, so I had to meticulously check such parts - I think this was hardest.

And unlike posts, books are media requiring very long breath for one topic, so front content and back content concepts shouldn’t differ, but since I never wrote such long texts, I had to periodically check front content and writing style while writing.

Still, after writing a book like this I feel proud and became much used to writing, so posting once or twice weekly isn’t very difficult, so overall it’s a good feeling. I hope many prospective readers reading this book feel it was beneficial. Especially I hope people starting frontend development for the first time read this book and think “Huh what, it’s not much?”

And finally, I want to give overwhelming thanks to beta readers who spared busy personal time reviewing the book and developer Kim Younghoon who proposed the good opportunity of technical book writing.

By the way, my book can be seen at Yes24, but since first edition printing hasn’t finished yet, delivery is possible from next month.

But rather than buying books online, I want to recommend going to offline bookstores like Kyobo Bookstore when the book stocks later, reading once, and buying. Just having future readers reading this go to Kyobo Bookstore, see the mint cover with coffee illustration, remember me, and open the book - that alone would make me happy.

That’s all for this post on an ordinary developer’s journey to authorship.