Sådan skriver du din første tekniske bog: Værktøjer, teknikker og ressourcer til førstegangsudviklerforfattere

For nylig skrev jeg min første tekniske bog - ja, jeg afsluttede den endelig. ?

Dette projekt var længe på min liste. Og nu hvor jeg endelig har afsluttet det, vil jeg gerne dele min oplevelse med alle.

I dette indlæg forsøgte jeg at dokumentere min komplette rejse med at skrive bogen. Jeg diskuterer alt motivation og forhindringer for værktøjer, teknikker og ressourcer.

Min bog fokuserer på Hyperledger Composer Blockchain-værktøjet. Det er helt gratis og er lige nu kun tilgængeligt i PDF-format.

Alle disse punkter er lige så nyttige til teknisk blogskrivning. Så lad os komme i gang og dykke ned i det, jeg lærte.

Motivering

Jeg har skrevet tekniske artikler og tutorials siden slutningen af ​​2018. Nu er jeg ganske fortrolig med processen med at skrive en artikel eller en tutorial. Jeg forstår, hvordan jeg skal nærme mig artiklen, og hvilke værktøjer jeg skal bruge.

Men når det kommer til bogskrivning - og især en teknisk bog - er arenaen helt anderledes.

Min motivation var nysgerrighed. Jeg spekulerede på, hvordan forfattere skriver bøger. Hvad er deres tankeproces? Hvilke værktøjer bruger de? Og selvfølgelig, hvordan føles det at skrive en bog? ?

Jeg er softwareingeniør, og jeg har arbejdet på Blockchain siden 2018. Jeg har lært om forskellige blockchains som Ethereum og Hyperledger Fabric. Jeg har også brugt mange værktøjer som trøffel, remix og hyperledger-komponist.

Der var et par forskellige ting, jeg ønskede at skrive om, som Ethereum eller Hyperledger Fabric .

Men da det var min første bog, var disse emner ikke ideelle for mig. De ville have krævet meget mere tid og kræfter, end jeg kunne give. Så jeg valgte en simpel: Hyperledger Composer.

Første forhindring

Før jeg kom i gang, spekulerede jeg på, hvilket værktøj eller redaktør jeg skulle bruge til at skrive bogen.

Skal jeg skrive i MS Word, Google Docs eller bruge noget andet?

Det største problem var, hvordan man formaterede kodestykker korrekt. Disse redaktører er ikke designet til teknisk skrivning.

Der er forskellige måder at tilføje kode på, men det kræver yderligere formatering.

Jeg læste mange artikler om hvilke gode værktøjer der er tilgængelige til teknisk bogskrivning. Jeg prøvede mange af dem, men jeg var ikke tilfreds med nogen af ​​dem. Jeg spildte meget tid på at finde det perfekte værktøj.

Til sidst indså jeg, at redaktører kun letter skriveprocessen og gjorde administrationen af ​​bogen enklere. Men hvad der virkelig betyder noget er indholdet. Så jeg stoppede med at søge efter den perfekte editor og gik til det grundlæggende.

Grundlæggende: VS-kode

Jeg brugte min foretrukne kodeditor til at skrive bogen. Ja, VS-kode ?

Efter at have brugt dage på at søge rundt på Internettet foreslog ikke en enkelt artikel, at du havde brug for noget specifikt værktøj eller redaktør til at skrive en teknisk bog. VS Code eller Atom ville være mere end nok.

Jeg skrev hele bogen i VS-kode i mit foretrukne markdown-format. For at gøre min skrivning lettere brugte jeg et par markdown-plugins som Markdown All in One og Markdown Preview Enhanced .

Det første plugin hjælper dig med at skrive markdown, mens det andet hjælper i preview-tilstand. Det viser, hvordan markdown vil se ud og opføre sig efter konvertering til HTML eller andre formater.

Markdown All in One har også en forhåndsvisningstilstand, men Markdown Preview Enhanced har flere temaer og muligheder for at eksportere markdown-filen i HTML, PDF og andre læsbare formater som epub eller Mobi.

Bare en heads up - disse andre formater kræver, at du installerer Pandoc på din maskine.

Jeg er Windows-bruger. For Mac-brugere fandt jeg, at der er mange gode redaktører tilgængelige som bjørn, ulysses og mange andre.

For nylig opdagede jeg, at der er mange markdown-redaktører tilgængelige på Windows og MacOS, som du kan bruge til bogskrivning. Tjek Notion, Typora, iA Writer og SimpleNote.

Bundlinje Spild ikke for meget tid på at finde den perfekte editor . Bare start med at skrive i din valgte redaktør. Med tiden vil du finde ud af det.

Anden forhindring

Så begyndte jeg at spørge mig selv, hvorfra skulle jeg begynde at skrive? Hvordan skal jeg skrive? Hvordan skal jeg nærme mig det?

Kort sagt ville jeg vide, hvordan jeg skulle skrive denne bog, så læseren kunne få mest muligt ud af den.

Disse spørgsmål fik mig til at ridse hovedet meget. I begyndelsen ændrede jeg min tilgang 4 eller 5 gange.

På dette tidspunkt foreslår jeg at bruge lidt tid på at virkelig overveje din tilgang. For når du først er midt i bogen, bliver det ikke en nem opgave at ændre den.

Stil spørgsmålene

Jeg stillede mig selv disse spørgsmål om bogen og noterede mine tanker nede.

  1. Hvem er min målgruppe? Er de begyndere, mellemliggende eller eksperter?
  2. Har de brug for noget forudgående kendskab til emnet?
  3. Hvordan skal jeg organisere bogen?
  4. Hvordan skal jeg navngive filerne eller kapitlerne, så det er let at finde hvert emne?
  5. Hvordan skal jeg spore mine fremskridt?
  6. Hvordan skal jeg vedligeholde versionerne af bogens kapitler og kladder? Der vil være en række lejligheder, hvor sidste redigering faktisk var meget bedre end den nuværende version.

Dette er et par grundlæggende spørgsmål, som jeg stillede, og de var nyttige.

Min tilgang

Jeg vil nu beskrive den tilgang, jeg tog med at skrive denne bog.

Opret en todo-liste

Først oprettede jeg en opgaveliste. På denne liste noterede jeg alle hovedpunkter, emner, underemner, referencer, forord, omslag, titel og så videre.

Jeg tilføjede stort set alle de tanker, der kom til at tænke på bogen.

Jeg vil foreslå at oprette to todo-lister: en på papir og det samme som en blød kopi.

Først skal du notere alle punkterne på papiret. Når du har noteret alt, skal du læse det 2-3 gange. Så uanset nye ideer dukker op i dit hoved, skal du notere dem.

For eksempel, hvis du tænker på, hvordan du skal forklare et bestemt emne, skal du notere det. Det vil gøre dit arbejde meget lettere. Så når du begynder at skrive om dette emne, kan du henvise til disse noter.

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.

om mig-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.

tak-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? ?

bogomslag

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.

licens

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

Forsidefoto af Thought Catalogue på Unsplash