# Writing a book
in 2018
February 22nd 2018 • [Front-end London][] {.footer}
[Front-end London]: https://www.frontendlondon.co.uk/archive#fel45
@@@
# Writing a _technical_
book in 2018
February 22nd 2018 • [Front-end London][] {.footer}
[Front-end London]: https://www.frontendlondon.co.uk/archive#fel45
@@@
# A _developer_
_writing_ a book
printed on _paper_ in an open source way
@@@
# A journey about
a *web developer* and
a *book publisher*.
Not so much about how painful it is to write an actual 300 pages book.
Watch [What I learned writing a lousy tech book][] (WTD 2014). {.footer}
[What I learned writing a lousy tech book]: https://www.youtube.com/watch?v=w1L2SgQuv6Q
## Hi, I'm **Thomas**
A 🥖🧀 living in 🇬🇧
@@@
## software designer
full stack engineer, user research, open source,
agile facilitation, mentoring, etc.
[https://thom4.net]() • [@thom4parisot](https://twitter.com/thom4parisot) {.footer}
@@@
## ~~BBC R&D~~ dtc innovation
a not-for-profit **cooperative company**
open source and open data projects
Bordeaux • London • Montréal
[dtc-innovation.org](https://dtc-innovation.org/) {.footer}
## Context • Writer Experience • Modular Tooling • Publishers • Community Engagement
@@@
# 🕐 2008
@@@
## Me: Fancy a short essay on blah?
## Publisher: Sure! Actually a _book_ would be better!
## Me: 😅
@@@
@@@
@@@
@@@
@@@
@@@
@@@
# 🕐 2014
@@@
## Me: Fancy a _Node.js_ book?
## Publisher: Sure! send me your _ODT_ copy in 6 months.
## Me: 😅
## Context • **Writer Experience** • Modular Tooling • Publishers • Community Engagement
@@@
## **Playful**
Learning by doing, fully working examples.
@@@
## **Friendly**
No assumption on who the reader is, close to the common language.
@@@
## **Open**
To read online, to contribute, to review.
@@@
## What does it mean,
to write a _book as a software_ application?
@@@
```sh
git clone https://github.com/thom4parisot/nodebook
```
@@@
@@@
@@@
@@@
## _Comfortable_ syntax
[Asciidoc][] predates Markdown. [Asciidoctor][] is a superset written in Ruby and JavaScript.
[Asciidoc]: http://www.methods.co.nz/asciidoc/
[Asciidoctor]: https://asciidoctor.org/
@@@
```adoc
= Hello, AsciiDoc!
:author: Doc Writer <doc@example.com>
:toclevel: 4
An introduction to http://asciidoc.org[AsciiDoc].
== First Section
* item 1
* item 2
[source,ruby]
puts "Hello, World!"
```
@@@
## _Comfortable_ writing software
@@@
@@@
## _Comfortable_ code editor
@@@
@@@
@@@
@@@
## ~~Developing~~ Writing in the open
@@@
@@@
@@@
## Context • Writer Experience • **Modular Tooling** • Publishers • Community Engagement
@@@
## Writing _Code_
@@@
@@@
@@@
@@@
## Code _quality_ for free
@@@
@@@
## Asciidoc on GitHub is not enough
@@@
@@@
## _Building_ the book
```sh
$ make build-html
```
@@@
@@@
## _Automating_ all the way
Repeated manual tasks are good candidates.
@@@
@@@
@@@
@@@
## _Packaged_ code and content
What if I could do `npm install nodebook`?
@@@
@@@
@@@
## _Media_ query
A ~~picture~~ video is worth 1000 words (when you can play a video)
@@@
@@@
@@@
@@@
## Built with Asciidoctor.js
Building a Node.js book with Node.js 🙌
@@@
@@@
## ✨ Extending _Asciidoctor.js_ ✨
@@@
## _Interactive_ code
Run and tweak code in your browser.
@@@
@@@
@@@
## Grab it on _npm_
👉 [npmjs.com/asciidoctor-extension-interactive-runner][runner]
[runner]: http://npmjs.com/asciidoctor-extension-interactive-runner
@@@
## Copy/paste bash commands
Hat tip to [Remy Sharp][]
👉 [remysharp.com/2017/03/27/dollar-in-code-examples][dollar-code] {.footer}
[dollar-code]: https://remysharp.com/2017/03/27/dollar-in-code-examples
[Remy Sharp]: https://remysharp.com/
@@@
## MDN web docs _macro_
Expand it to an admonition block • eg: `mdn::global[RegExp]`
@@@
@@@
## Context • Writer Experience • Modular Tooling • **Publishers** • Community Engagement
@@@
## Publishers are good at _publishing_
Sourcing authors • Styling ODT files • Sending to printer • Shipping to stores • Payroll and taxes
@@@
## Publishers could be good at _GitHub_
Text reviews (grammar, spelling) • tasks automation
@@@
@@@
@@@
## Good at _books_
@@@
@@@
## Less good at _dealing with content_
@@@
@@@
@@@
## _Hamster wheel_ syndrome
Not enough time nor vision to streamline
## Context • Writer Experience • Modular Tooling • Publishers • **Community Engagement**
@@@
## 2017 writing residency
3 months writing in _trains_, visiting _friends_ and learning from _peers_.
@@@
@@@
@@@
## _Meetups_
Reality check • each crowd has their own problems/culture/focuses.
@@@
@@@
## _Workshops_
2h mob programming sessions • reading out loud •
pair writing • code reviews
@@@
@@@
@@@
@@@
## _Energy_ management
Writing is strenuous. We have a _different pace_. Finding a balance in writting _alone_, _social_ workshops and _triaging_ issues on GitHub.
# Wrap up
@@@
## _No_ dialogue ➡️ _poor_ writing experience
Publishers in hamster wheels • Writers don't know about alternatives.
@@@
@@@
## Writing _correlates_ tooling
Text ∞ Feedback ∞ Feature ∞ Feedback
@@@
## _Derivable_ content
Paper (offline) • web (interactive) • npm (all in one)
@@@
## _Debuggable_ content
Agile practices apply to writing.
@@@
## Modularity
Building blocks _on top of_ content.
@@@
## What about _non-developer_ writers?
@@@
@@@
## _Licensing_ is fuzzy
Do contributors get paid for a paragraph? Or raising issues on GitHub?
@@@
## _Balance_
Pacing out the _content_ structure, writing _pace_. Finishing things helps!
~~~~
_Failed_ attempts: Nights + week-ends, part time, etc.
Reminder: writing long form is strenuous (at least for me).
@@@
## Writing should be _fun_
If it is not, it's about making it a _creative activity_.
@@@
## Next: _ship it_!
ETA June 2018. 4 years later, not too bad…
@@@
## Next: Sciences du Design
_Featured article_ about mixing software/text/tooling for publishing purposes.
[sciences-du-design.org/en](http://www.sciences-du-design.org/en/) {.footer}
# Merci 😊
Give a shout to [@thom4parisot](https://twitter.com/thom4parisot) or talk to me later.
@@@