Az első műszaki könyv megírása: Eszközök, technikák és források az első fejlesztői szerzők számára

Nemrég írtam az első szakkönyvemet - igen, végül elkészültem. ?

Ez a projekt sokáig szerepelt a listámon. És most, hogy végre elkészültem, mindenkivel szeretném megosztani a tapasztalataimat.

Ebben a bejegyzésben megpróbáltam dokumentálni a könyv megírásának teljes útját. Megbeszélek minden motivációt és akadályt az eszközök, technikák és források előtt.

Könyvem a Hyperledger Composer Blockchain eszközre összpontosít. Teljesen ingyenes, és jelenleg csak PDF formátumban érhető el.

Mindezek a pontok egyformán hasznosak a technikai blogíráshoz. Kezdjük tehát, és merüljünk el a tanultakban.

Motiváció

2018 vége óta írok technikai cikkeket és oktatóanyagokat. Mostanra már nagyon jól érzem magam egy cikk vagy egy oktatóanyag írásának folyamatában. Megértem, hogyan kell megközelíteni a cikket, és mely eszközöket kell használnom.

De ami a könyvírást - és főleg a szakkönyvt illeti - az aréna egészen más.

A motivációm a kíváncsiság volt. Kíváncsi voltam, hogyan írnak a szerzők könyveket. Mi a gondolkodásuk? Milyen eszközöket használnak? És persze, milyen érzés könyvet írni? ?

Szoftvermérnök vagyok, és 2018 óta dolgozom a Blockchain-on. Megismertem a különböző blokkláncokat, mint például az Ethereum és a Hyperledger Fabric. Számos eszközt is használtam, például szarvasgomba, remix és hiperkönyves zeneszerző.

Néhány különböző dologról akartam írni, mint például az Ethereum vagy a Hyperledger Fabric .

De mivel ez volt az első könyvem, ezek a témák nem voltak ideálisak számomra. Sokkal több időre és erőfeszítésre lett volna szükségük, mint amennyit tudtam adni. Szóval egy egyszerűt választottam: Hyperledger Composer.

Első akadály

A kezdés előtt arra gondoltam, melyik eszközt vagy szerkesztőt kell használnom a könyv megírásához.

Írjak MS Word-ben, Google Docs-ban, vagy használjak valami mást?

A fő kérdés a kódrészletek helyes formázása volt. Ezeket a szerkesztőket nem műszaki írásra tervezték.

Különböző módszerek vannak a kód hozzáadásához, de ez további formázást igényel.

Sok cikket olvastam arról, hogy milyen jó eszközök állnak rendelkezésre a technikai könyvíráshoz. Sokukat kipróbáltam, de egyiküknek sem örültem. Sok időt pazaroltam a tökéletes eszköz megtalálására.

Végül rájöttem, hogy a szerkesztők csak megkönnyítik az írási folyamatot és egyszerűbbé teszik a könyv kezelését. De ami igazán számít, az a tartalom. Tehát abbahagytam a tökéletes szerkesztő keresését, és az alapokhoz fordultam.

Az alapok: VS kód

A könyv megírásához a kedvenc kódszerkesztőmet használtam. Igen, VS kód ?

Miután napokat töltött az interneten való keresgéléssel, egyetlen cikk sem javasolta, hogy bármilyen speciális eszközre vagy szerkesztőre van szüksége egy szakkönyv megírásához. A VS Code vagy az Atom több mint elég lenne.

Az egész könyvet VS Code- ban írtam a kedvenc markdown formátumomban. Az írásom megkönnyítése érdekében használtam néhány markdown plugint, mint például a Markdown All in One és a Markdown Preview Enhanced .

Az első plugin segít leírást írni, míg a második előnézeti módban. Megmutatja, hogyan fog kinézni és hogyan fog viselkedni a jelölés HTML vagy más formátumokká konvertálása után.

A Markdown All in One előnézeti móddal is rendelkezik, de a Markdown Preview Enhanced több témával és lehetőséggel rendelkezik a markdown fájl HTML, PDF és más olvasható formátumokban, például epub vagy Mobi exportálásához.

Csak egy figyelmeztetés - ezek a más formátumok megkövetelik, hogy telepítse a Pandoc -ot a gépére.

Windows-felhasználó vagyok. A Mac-felhasználók számára számos nagyszerű szerkesztőt találtam, mint például a bear, ulysses és még sokan mások.

A közelmúltban rájöttem, hogy a Windows és a MacOS rendszeren számos jelölőszerkesztő áll rendelkezésre, amelyeket könyvíráshoz használhat. Nézze meg a Notion, Typora, iA Writer és a SimpleNote oldalakat.

A lényeg: Ne pazaroljon túl sok időt a tökéletes szerkesztő megtalálásához . Csak írjon a kívánt szerkesztőbe. Idővel rájössz.

Második akadály

Aztán elkezdtem kérdezni magamtól, honnan kezdjem az írást? Hogyan írjak? Hogyan álljak hozzá?

Röviden, szerettem volna tudni, hogyan kell pontosan megírnom ezt a könyvet, hogy az olvasó a lehető legtöbbet hozza ki belőle.

Ezek a kérdések nagyon megvakarták a fejem. Az elején négyszer vagy ötször változtattam a szemléletemet.

Ezen a ponton azt javaslom, szánjon egy kis időt arra, hogy valóban elgondolkodjon a megközelítésén. Mert ha már a könyv közepén állsz, nem lesz könnyű feladat megváltoztatni.

Tedd fel a kérdéseket

Feltettem magamnak ezeket a kérdéseket a könyvvel kapcsolatban, és megjegyeztem a gondolataimat.

  1. Ki a célközönségem? Kezdők, középhaladók vagy szakértők?
  2. Szükségük van valamilyen előzetes ismeretre a témában?
  3. Hogyan kell megszervezni a könyvet?
  4. Hogyan nevezzem el a fájlokat vagy fejezeteket, hogy könnyen megtalálja az egyes témákat?
  5. Hogyan kell követnem a fejlődésemet?
  6. Hogyan kell fenntartani a könyv fejezeteinek és vázlatainak változatait? Számos olyan alkalom lesz, amikor a legutóbbi szerkesztés sokkal jobb volt, mint a jelenlegi verzió.

Ez néhány alapvető kérdés, amelyet feltettem, és hasznosak voltak.

Az én megközelítésem

Most leírom azt a megközelítést, amelyet a könyv megírásához használtam.

Hozzon létre egy Todo listát

Először létrehoztam egy tennivalók listáját. Ebben a listában feljegyeztem az összes fő pontot, témát, altémát, referenciákat, előszót, borítót, címet és így tovább.

Nagyjából hozzáfűztem az összes gondolatot, ami eszembe jutott a könyvvel kapcsolatban.

Azt javaslom, hogy hozzon létre 2 Todo listát: egyet papíron és ugyanazt, mint puha példányt.

Először jegyezze fel a papír összes pontját. Miután mindent feljegyzett, olvassa el 2-3 alkalommal. Aztán bármilyen új ötlet is felbukkan a fejedben, jegyezd fel őket.

Például, ha belegondol, hogyan magyarázza el egy adott témát, jegyezze fel. Sokkal könnyebbé teszi a munkáját. Majd amikor elkezdesz erről a témáról írni, hivatkozhatsz ezekre a megjegyzésekre.

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