In this talk the speaker explains and demonstrates popular tools and platforms for writing and publishing technical documentation, such as developer's guides, technical books, API documentation and technical tutorials, along with his personal experience from the last 15 technical books published online using such tools. Toolchains for building beautiful, flexible and searchable documentation like gitbook-cli, MkDocs and Sphinx are discussed and demonstrated, along with platforms like Read The Docs (readthedocs.org) and GitBook (gitbook.com). In a live demonstration, the speaker shows an example how to write an open-source technical book in GitHub, using Markdown articles, compiled into a single online book using the "gitbook-cli" static site generator and how to publish the book in GitHub Pages. A special attention is given to more advanced techniques like embedding videos and live code examples (with [Run] button) in a smart way in Gitbook books. Learn more at https://github.com/beerjs/sofia, https://nakov.com.

1. Aug 1, 2019
let title = “Creating Technical Documentation”;
let info = {
speaker: “Svetlin Nakov”,
position: “Co-founder @ SoftUni, blockchain technical trainer”,
author-url: “https://nakov.com”
};
let subTitle = “Guidelines for Developers”;

2. Aug 1, 2019
About Svetlin Nakov
• Software engineer, trainer, PhD,
entrepreneur, author of 15 books,
devoted to tech education
• 3 successful tech educational initiatives:

3. Aug 1, 2019
agenda();
• Documentation Tools for Developers
o gitbook-cli, MkDocs, Sphinx
• Cloud-Based Documentation Platforms
o Read The Docs (readthedocs.org)
o GitBook (gitbook.com)
• Examples from My Experience
o https://csharp-book.softuni.org
o Video Embed and Code Runner plugins

4. Aug 1, 2019
Documentation Tools
for Developers
gitbook-cli, MkDocs, Sphinx

5. Aug 1, 2019
gitbook-cli
• gitbook-cli
o https://github.com/GitbookIO/gitbook-cli
• Build a GitBook Documentation
o https://gist.github.com/nakov/ff4758eafa2d2d1296a75aa91ca
c1ddf
• Deploy a GitBook at GitHub Pages
o https://gist.github.com/nakov/ff4758eafa2d2d1296a75aa91ca
c1ddf

6. Aug 1, 2019
GitBook: Documentation Structure
• GitBook-CLI:
Markdown 
static HTML

7. Aug 1, 2019
GitBook: A Compiled Documentation

8. Aug 1, 2019
MkDocs: Python-based Documentation Builder
• MkDocs: converts markdown (.md) to static HTML site

9. Aug 1, 2019
Sphinx-Doc: Python-based Doc Builder
• Sphinx: converts
reStructuredText
(.rst) to static
HTML site

10. Aug 1, 2019
Cloud-Based
Documentation Platforms
ReadTheDocs.org, GitBook.com

11. Aug 1, 2019
ReadTheDocs.org
• Cloud-based Sphinx-Docs and MkDocs compiler &
book hosting platform
o ReadTheDocs.org: free, open-source, non-commercial
o ReadTheDocs.com: paid service for enterprises

12. Aug 1, 2019
GitBook.com
• It was cloud-based gitbook-cli compiler & hosting platform
o Static site generator: markdown to HTML (until 2018)
• The new version (GitBook V2) is no longer-compatible
o Server-based, not static file generator
o Incompatible, inextensible, not recommended!

13. Aug 1, 2019
Examples from
My Experience
https://csharp-book.softuni.org

14. Aug 1, 2019
C# Basics Book and Videos
• https://csharp-book.softuni.org • Made with
gitbook-cli
• Hosted at
GitHub Pages
• Custom "video
embed" plugin
• Custom "code
embed" plugin

15. Aug 1, 2019
"Code Embed" Plugin for GitBook
• https://gist.github.com/nakov/1d0a322640c0a9ffb7841ac9598cc926

16. Aug 1, 2019
"Video Embed" Plugin for GitBook
• https://gist.github.com/nakov/1d0a322640c0a9ffb7841ac9598cc926

17. Aug 1, 2019
Other Examples from My Experience
https://cryptobook.nakov.com
https://js-book.softuni.bg
https://java-book.softuni.bg
https://python-book.softuni.bg
https://csharp-book.softuni.bg

18. Aug 1, 2019
Thanks to our Sponsors