how developers write documentation
TRANSCRIPT
![Page 1: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/1.jpg)
How developers code write@sengopal
![Page 2: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/2.jpg)
What is Documentation
![Page 3: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/3.jpg)
What is DocumentationMaterial that provides official information or evidence
or that serves as a record.
Written specification and instructions accompanying a computer program.
![Page 4: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/4.jpg)
Aspects
READABILITYAvailable Offline
No custom tools
Standard Templates
EDITORAvailable Offline
No custom tools
Basic In built generators for TOC,
tables etc.,
Reviews
DISTRIBUTIONVersioned
Zero staleness
Close to source of truth
![Page 5: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/5.jpg)
Available Todayhttps://xkcd.com/927/
![Page 6: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/6.jpg)
Google Docs
Microsoft Word
Wiki
O365
What’s the point of this presentation anyway?
![Page 7: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/7.jpg)
GITHUBAvailable Offline
No custom tools
Versioned and Reviews
Close to source of truth
Zero staleness
Templates - define your own!
this←
![Page 8: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/8.jpg)
Lingua Franca
MARKDOWN
Released in 2004
Lightweight markup
Plain text formatting
Converted to HTML
Readme files
Online forums
ASCIIDOC
Released in 2002
Equivalent to DocBook
Plain-text mark-up
DocBook tool-chain
PDF, TeX, manpages, e-books, slides, Git
![Page 9: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/9.jpg)
![Page 10: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/10.jpg)
![Page 11: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/11.jpg)
Choicehttp://counterinception.com/sites/default/files/pictures/MatrixBluePillRedPill.jpg
![Page 12: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/12.jpg)
AsciidocWhy book writers are switching to Asciidoc
1.Better UI control
2.Admonitions
3.Macros such as TOC
4.Env. Variables
5.Advanced Table support
6.Page Navigation
7.More….
Asciidoc Reference
![Page 13: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/13.jpg)
My Toolset
![Page 14: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/14.jpg)
ToolsetGithub
Asciidoc
AsciidocFx
Atom/Chrome Plugin
![Page 15: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/15.jpg)
Side Note
GithubWikiGollum
Static Site Generators
staticgen
![Page 16: How developers write documentation](https://reader034.vdocuments.mx/reader034/viewer/2022052418/58a2ed7a1a28abc9648b6e4d/html5/thumbnails/16.jpg)
Questions?