Як написати свою першу технічну книгу: Інструменти, методи та ресурси для авторів, які вперше розробляють

Нещодавно я написав свою першу технічну книгу - так, нарешті я її закінчив. ?

Цей проект був у моєму списку довгий час. І тепер, коли я нарешті його закінчив, я хотів би поділитися своїм досвідом з усіма.

У цьому дописі я намагався задокументувати свою повну подорож написанням книги. Я обговорюю всі мотивації та перешкоди для інструментів, прийомів та ресурсів.

Моя книга присвячена інструменту Hyperledger Composer Blockchain. Він повністю безкоштовний і зараз доступний лише у форматі PDF.

Усі ці моменти однаково корисні для технічного написання блогу. Тож давайте почнемо і зануримось у те, що я дізнався.

Мотивація

Я пишу технічні статті та навчальні посібники з кінця 2018 року. На сьогоднішній день я цілком відчуваю процес написання статті чи навчального посібника. Я розумію, як підходити до статті та які інструменти слід використовувати.

Але що стосується написання книг - і особливо технічної книги - арена зовсім інша.

Мотивацією стала допитливість. Я дивувався, як автори пишуть книги. Який у них процес мислення? Які інструменти вони використовують? І звичайно, як відчуваєш написання книги? ?

Я інженер-програміст, і працюю над Blockchain з 2018 року. Я дізнався про різні блокчейни, такі як Ethereum та Hyperledger Fabric. Я також використовував багато інструментів, таких як трюфель, ремікс та композитор гіперледжерів.

Про декілька різних речей, про які я хотів написати, як Ethereum чи Hyperledger Fabric .

Але оскільки це була моя перша книга, ці теми для мене не були ідеальними. Вони вимагали б набагато більше часу та зусиль, ніж я міг би дати. Отже, я вибрав простий: Hyperledger Composer.

Перша перешкода

Перед початком роботи я замислювався, яким інструментом чи редактором мені слід писати книгу.

Чи слід писати в MS Word, Google Docs чи використовувати щось інше?

Основною проблемою було те, як правильно форматувати фрагменти коду. Ці редактори не призначені для технічного написання.

Для додавання коду існують різні способи роботи, але для цього потрібно додаткове форматування.

Я прочитав багато статей про те, які хороші інструменти доступні для технічного написання книг. Я пробував багато з них, але жоден з них не був задоволений. Я витратив багато часу на пошук ідеального інструменту.

Врешті-решт, я зрозумів, що редактори лише полегшують процес написання та спрощують управління книгою. Але насправді важливим є зміст. Отже, я перестав шукати ідеального редактора і пішов до основ.

Основи: VS Code

Для написання книги я використовував улюблений редактор коду. Так, код VS ?

Провівши дні пошуків в Інтернеті, жодна стаття не підказувала, що для написання технічної книги вам потрібен якийсь конкретний інструмент або редактор. VS Code або Atom було б більш ніж достатньо.

Я написав цілу книгу у VS Code у своєму улюбленому форматі знижки. Для полегшення мого написання я використав пару плагінів, як Markdown All in One та Markdown Preview Enhanced .

Перший плагін допомагає писати націнку, а другий - у режимі попереднього перегляду. Він показує, як виглядатиме і поводитиметься знижка після перетворення її в HTML або інші формати.

Markdown All in One також має режим попереднього перегляду, але Markdown Preview Enhanced має кілька тем та опцій для експорту файлу розмітки у HTML, PDF та інші читабельні формати, такі як epub або Mobi.

Попередження - для інших форматів потрібно встановити Pandoc на свою машину.

Я користувач Windows. Для користувачів Mac я виявив, що доступно багато чудових редакторів, таких як ведмідь, Улісс та багато інших.

Нещодавно я виявив, що в Windows та MacOS доступно багато редакторів націнки, які можна використовувати для написання книг. Перевірте Notion, Typora, iA Writer та SimpleNote.

Підсумок Не витрачайте занадто багато часу на пошук ідеального редактора . Просто починайте писати у вибраному редакторі. З часом ви це зрозумієте.

Друга перешкода

Тоді я почав запитувати себе, з чого мені почати писати? Як мені писати? Як мені підійти до цього?

Коротше кажучи, я хотів знати, як саме я повинен написати цю книгу, щоб читач отримав від неї максимум користі.

Ці питання змусили мене сильно почухати голову. На початку я змінив свій підхід 4 або 5 разів.

На цьому етапі я пропоную витратити трохи часу, щоб реально обдумати ваш підхід. Оскільки ви потрапили в середину книги, змінити її буде непростим завданням.

Задайте питання

Я задав собі ці запитання щодо книги і записав свої думки.

  1. Хто моя цільова аудиторія? Вони новачок, середній рівень або експерт?
  2. Чи потрібні їм попередні знання з цього предмету?
  3. Як мені упорядкувати книгу?
  4. Як слід назвати файли чи глави, щоб було легко знайти кожну тему?
  5. Як слід відстежувати свій прогрес?
  6. Як слід підтримувати версії розділів та чернетки книги? Буде кілька випадків, коли останнє редагування насправді було набагато кращим за поточну версію.

Це декілька основних питань, які я задав, і вони були корисні.

Мій підхід

Зараз я опишу підхід, який я застосував до написання цієї книги.

Створіть список завдань

Спочатку я створив список справ. У цьому списку я зазначив усі основні моменти, теми, підтеми, посилання, передмову, обкладинку, заголовок тощо.

Я майже додав усі думки, які мені спали на думку про книгу.

Я б запропонував створити 2 списки завдань: один на папері і такий самий як м’яка копія.

Спочатку запишіть усі моменти на папері. Як тільки ви все запишете, прочитайте 2-3 рази. Тоді, які б нові ідеї не з’являлись у вашій голові, запишіть їх.

Наприклад, якщо ви думаєте про те, як збираєтеся пояснити певну тему, запишіть це. Це значно полегшить вам роботу. Потім, коли ви починаєте писати на цю тему, ви можете звернутися до цих приміток.

Once you have a todo list on paper, create a soft copy and save all the points in chronological order.

This is what my todo list used to look like:

Tasks

  • [x] Index
  • [x] Cover
  • [x] Title
  • [x] Subtitle
  • [x] Preface
  • [x] What is Blockchain and Hyperledger Fabric?
  • [x] Introduction to Hyperledger Composer
  • [x] Environment Requirements and Setup
    • [x] Azure
    • [x] AWS
    • [x] GCP
  • [x] Project Objective
  • [x] Project Setup in Composer
  • [x] Model File
    • [x] Definition
    • [x] Modeling Language
    • [x] project code
  • [x] Script File
    • [x] Definition
    • [x] syntax
    • [x] project code
  • [x] Query File
    • [x] Definition
    • [x] Query Language
    • [x] project code
  • [x] ACL File
    • [x] Definition
    • [x] syntax
    • [x] project code
  • [x] Deployment in Composer Playground
  • [x] Testing in Composer Playground
  • [x] Export the .bna
  • [x] Composer Rest Server
  • [x] Frontend
  • [x] Conclusion
  • [x] References
  • [x] About Me
  • [x] Grammar Check 1
  • [x] Grammar Check 2
  • [x] Read the draft
  • [x] Read the final draft
  • [x] PDF format
  • [x] Add page no. to PDF
  • [x] New chapter starts from the new page
  • [x] Thank You Note
  • [x] License
  • [x] End cover

I used markdown format for my todo list. You can use whatever format is easiest for you.

Start Small but Do Start

Keep in mind that you don't need to write about each topic in order. There might be many topics which depend on previous topics, but others won't.

Also, you don't have to finish writing about the topic all at once either. Whatever topics you are feeling comfortable with, start there.

Your goal should be to start the book. Aim to write 10-20% of your book within a couple of weeks. Once you start, it will keep reminding you that you have to complete the book. In time you'll realize that this turns into a great motivator.

If there is a topic you don't know as much about, don't worry. Don't hesitate to get help from the Internet. Read how other people explained it. Take inspiration and then write about it in your way.

And remember – If you use any content from other people's work, make sure you inform them, cite it properly in your text, and list their work as a reference at the end.

Consider this as a professional courtesy. -- John Wick ?

Chronological Order

It took me a while to understand the importance of having a file naming convention.

At first I started following a Chapter 1, Chapter 2 naming convention for each topic. It turned out to be a terrible idea.

The problem with this naming scheme is that you have to maintain a separate file where you explain what is in the file. Or you have to open each file to see what it contains.

Another problem is that if you add a new chapter in between then you have to rename all the following chapters.

There are two conventions I found helpful, but each has its disadvantages.

One option is to use chapternumber-topic: Name the file as a chapter number followed by the topic of the chapter. Like this 10-Introduction-of-Blockchain.

Name the chapter number in 2 digits. This will help you add sub-sections to the same chapter in different files. Like this 11-History-of-Blockchain.

Another benefit of this naming convention is it will show all the files in the order of your book chapters.

Disadvantage: Adding new chapter in between requires that you rename all the following chapters.

The second option is to use filename as topic: Name all the files as the topic name. This will give you the freedom to write topics in random order. And you can maintain the order of the book in your todo list.

Disadvantage: All the files will be arranged in alphabetical order. After 10-15 files it will be difficult to track all the files, and it'll be harder to put them together in a draft.

In the end, I followed the second method. It worked alright for me.

To create a draft, I created a Node.js script. In this script, I entered all the topics in an array. Then I created a draft file and appended all the topics in it. Of course by reading them first ?. A few perks of being a Software Engineer ?.

This script was a saviour when I was editing. Many times I updated the topics or pictures within them. I fixed grammatical mistakes. Here Grammarly really saved me...but not completely as I was using the free version. ?

Chronicle of the book journey

Writing a book is not a sprint, it is a marathon. Always save your work when you complete a topic or are done for the day.

The next day, you might get a new idea for the same topic which you already completed. You might spend an hour on it, but it doesn't look good. In this case, UNDO is great but it also has limitations (and its limits vary from editor to editor). Do not test its limits too much.

Instead of relying on the editor or making duplicate copies, I used Git for version control. Don't think that git can only be used for managing your code. It is a versitile tool and its applications are only limited by your imagination.

For the readers who don't know about git:

Git is a distributed version control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files. --Wikipedia

You don't have to learn everything about git to use it for writing. The basic commands like init, add, commit, logs and checkout are more than enough for you to maintain your versions and keep your text accessible and safe.

There are many Git code hosting platforms available, like GitHub, GitLab and others. To host your book on one of these platforms, you can follow the below steps:

  1. Create an account. My personal choice is GitHub.
  2. Create a private repository with default choices. You can change its visibility to public in the future.
  3. Follow the instructions provided once the repository is created. Basically, in this step, you're connecting your local Git to your hosted repository.
  4. Learn 2 more commands, push and pull. Use push to push the local changes to the cloud repo and use pull to get the content from the cloud.

After this, whenever you make any changes, just add, commit and push. Simple, isn't it? ?

After a couple of commits, you will feel comfortable with git.

Check out this amazing article to learn more: Learn Git and Version Control in an Hour

The tools and resources I used

I used many tools and resources while writing, editing, formatting and designing the book.

Writing

For writing, I used the VS Code editor with a couple of markdown plugins, as I've discussed above.

For emojis, I used copy and paste emojis.

Editing

For correcting grammatical mistakes I used the free version of Grammarly. In the free version, it corrects all the basic mistakes like incorrect or missing articles, prepositions, commas, and so on.

I used the online pdf editor to add page numbers to the book.

Formatting

I used the Markdown in Preview plugin in VS Code to generate the PDF format. I used the default Git markdown formatting. You can change the formatting in the settings.

Page breaks in the PDF

As I was writing in markdown format, the PDF output was inconsistent. For example, it starts a new topic from the last page instead of from a new page.

To fix this, I used the page break html code at the end of each topic.

This will make the content that follows it start on a new page.

You can also add the end of the page-sequence like ***** this.

 ***** 

About Me Page

In the About Me section of my book, I divided the content into two columns: a brief about me and a profile picture.

It took me a while to realize the full capabilities of the markdown format. We can add plain html code in it. Here's what my "about me" page says:

 Hello, I am **_Shubham Kumar Chadokar_**. I am a Software Engineer and in my short career of almost 4 years, I've had the opportunity to work on Blockchain, Nodejs, Golang, and Docker. I've learned about other tech as well, but these are my primary focus. I love to write articles and tutorials on new tech by following a hands-on approach. This is my first book. Front end development isn't my specialty, and that's why I didn't include it in the book. If you have any queries or questions, please feel free to drop me an email. :e-mail: [[email protected]]([email protected]) :globe_with_meridians: [schadokar.dev](//schadokar.dev) [github.com/schadokar](//github.com/schadokar) 

For octacat, I used the img tag.

It looks like this.

about-me-3

Thank You Page

I added a thank you page to express my gratitude to the Hyperledger Composer Community for their work. I tried to add the content in the middle of the page.

 Thank You  I especially want to thanks the entire Hyperledger Composer Community for creating such an amazing tool. Many developers entered into the blockchain domain because of the simplicity of the composer.

It is unfortunate that it is deprecated but it sets a great example of easy automation, wrapping a complex Hyperledger Fabric into the easy to use Hyperledger Composer.

It looks like this.

thanks-note

Book Title and Sub-title

The book title should make the contents of the book clear in a few words or one short sentence.

While you're writing the book, note down all the keywords you use. This will help you to come up with a great title. You want to capture the essence of the book and let readers know, for example, whether it's theoretical or more hands-on.

A sub-title should give readers more detail about what they will get from this book or what they are going to learn.

A one sentence sub-title is ideal, and shouldn't be any longer than two sentences. Don't overdo it – let readers read the book. The idea is to give readers a taste of the complete book in one sentence but still not to tell anything ?.

My book title is Playtime with Hyperledger Composer and sub-title is Create a supply chain management project in Blockchain using Hyperledger Composer.

When you start writing your book, don't spend much time on the book title. When you finish writing, you'll be in a much better position to decide the book title. Everything is written, you know what it is all about, and what others will get from it.

In my case, I changed the book title and book cover at the last moment before publishing it. Before that, it was so boring ?.

Designing the Book Cover

You might have heard the idiom Don't judge a book by its cover.

But the harsh reality is, a book's cover is very important. It is the face of the book.

Try to keep it simple and informative. Don't overdo it. A simple title and a short subtitle with an image or two is more than enough.

I started designing the book cover by taking references from other books, and trying to edit them in Paint. The result was a complete disaster, and I couldn't think of anything good.

Then I realized that designing is not my cup of tea. I decided to hire a freelancer for this, so I checked out freelancing sites like UpWork and Fiverr.

Then, I found Canva. It's such a great tool. Amazing! ? ? ? ?

Canva is a graphic design platform that allows users to create social media graphics, presentations, posters and other visual content. It is available on web and mobile and integrates millions of images, fonts, templates and illustrations. Wikipedia

I used one of the templates from the canva book cover section and created my book cover. Not bad, right? ?

book-cover

License

I wrote this book out of curiosity and for fun. So, I wanted it to be free, and open-source, but I didn't want others to monetize it. Without a license, there are no restrictions.

I searched for a while and found a great answer on StackOverflow regarding free licenses, Creative Commons Licenses.

Creative Commons is a nonprofit organization that helps overcome legal obstacles to the sharing of knowledge and creativity to address the world’s pressing challenges.

They have provided a form with a couple of questions related to what kind of license you want. Fill out the form and voilà ?, your license is ready. Copy and paste it or use the embedded link.

license

Publishing your book

There are many options you can choose from to publish your book. You can approach a publishing house and send in your draft. If they want to publish you can go ahead and secure a deal.

After this, the publishing house takes care of other processes like formatting, editing your book, creating an attractive book cover, all the licensing, the publishing process, and most importantly marketing.

In short, if you want to monetize your book and you're expecting a good amount, then a publishing house is the best option available.

Another option is self-publishing. Yes, we can self-publish our own books. Amazon's Kindle Direct Publishing provides a great platform for this. It is free and it publishes the book worldwide.

You'll get 70% of the profits for each sale. The kdp take cares of all the publishing process. You just have to write the book, upload it and format it.

You simply enter the price you want to charge, along with some basic info about the book and and yourself. You can follow their tutorials for more info – they have done a great job.

But I wanted to keep my book free and didn't have the patience for the above processes. So, I self-published it without using any third party.

I just converted the book to PDF format and saved it in an AWS S3 Bucket so that anyone can download it. Then I hosted the book on my website. Simple. ?

Share your work

Once you complete your masterpiece, it is time to show it to the world.

If you haven't teamed up with a publisher or even if you did, you have to spread the word.

These are the few platforms I used, but don't limit yourself.

LinkedIn

LinkedIn is a professional platform and many developers are on it, no matter their specialty in the tech world. You'll also find people of every profession, you name it.

Share your work with them, ask for feedback. 90% of the time you'll get a reply. I shared my work with Dan Selmon, one of the Hyperledger Composer contributors, as well as Srinivas Mahankali, who wrote many books on Blockchain.

They were both very helpful and gave their honest feedback. I am thankful to Dan, who even offered to share the book among his network on LinkedIn and Twitter. ?

Reddit

Reddit is a community hub. You will find many active communities on various subjects here. You just have to join the community that's relevant to your work and share it there.

You'll find a lot of active members on Reddit, in these groups, and they are not shy to share their opinion. If there is a room for improvement, some of them might offer to help.

But before sharing, DO READ THE GUIDELINES. If you violate any of them, they will remove your post.

Twitter

Twitter is not just a social platform where people share their opinions. So don't underestimate it.

If you like facts and figures, here you go: there are 1.3+ billion accounts on Twitter, 330 million monthly active users, 152 million daily active users and 500 million tweets per day. This is huge.

You just have to craft your message and select the right keywords within the 280 characters limit and you can potentially reach a large audience.

Blogs

Do some research and figure out which publications or digital magazines publish articles in your book's category. Share your book summary and details with them.

Ask them if they can write an article about your book. Or you can write an article about your book and share the draft with those publications.

There are also many other platforms you can try – just do a bit of digging.

Conclusion

This was my first experience writing a book. It took some time but it was worth it. Now, I have another badge on my portfolio. ?

I learned a lot from this experience. This article serves as documentation of all my learning for anyone who wants to write their first book or their next book.

Below is the final list of tools I've used so far.

Any suggestions for others are most welcome.

Thank you for reading and don't forget to share your first book with me. ?

Final List of Tools I used

  • Editor: Visual Studio Code with 2 Markdown plugins
  • Versioning Tool:Git and GitHub
  • Emojis: Copy and Paste emojis
  • Grammar Check: Grammarly
  • License: Creative Commons Licenses
  • Cover Design: Canva
  • PDF page number: online pdf editor
  • eBook storage: AWS S3 bucket.
  • Book Hosting: On my blog

Thanks for Reading

If you have any feedback or suggestions to help me improve this article please connect with me on twitter or email me.

  • Read my other articles
  • Subscribe to My Newsletter

Cover photo by Thought Catalog on Unsplash