O slideshow foi denunciado.
Utilizamos seu perfil e dados de atividades no LinkedIn para personalizar e exibir anúncios mais relevantes. Altere suas preferências de anúncios quando desejar.

Creating Technical Documentation - Nakov at Beer.js - August 2019

138 visualizações

Publicada em

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.

Publicada em: Software
  • Seja o primeiro a comentar

  • Seja a primeira pessoa a gostar disto

Creating Technical Documentation - Nakov at Beer.js - August 2019

  1. 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. 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. 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. 4. Aug 1, 2019 Documentation Tools for Developers gitbook-cli, MkDocs, Sphinx
  5. 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. 6. Aug 1, 2019 GitBook: Documentation Structure • GitBook-CLI: Markdown  static HTML
  7. 7. Aug 1, 2019 GitBook: A Compiled Documentation
  8. 8. Aug 1, 2019 MkDocs: Python-based Documentation Builder • MkDocs: converts markdown (.md) to static HTML site
  9. 9. Aug 1, 2019 Sphinx-Doc: Python-based Doc Builder • Sphinx: converts reStructuredText (.rst) to static HTML site
  10. 10. Aug 1, 2019 Cloud-Based Documentation Platforms ReadTheDocs.org, GitBook.com
  11. 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. 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. 13. Aug 1, 2019 Examples from My Experience https://csharp-book.softuni.org
  14. 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. 15. Aug 1, 2019 "Code Embed" Plugin for GitBook • https://gist.github.com/nakov/1d0a322640c0a9ffb7841ac9598cc926
  16. 16. Aug 1, 2019 "Video Embed" Plugin for GitBook • https://gist.github.com/nakov/1d0a322640c0a9ffb7841ac9598cc926
  17. 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. 18. Aug 1, 2019 Thanks to our Sponsors