Bonjour et bienvenue à Mix-IT. Merci d’être présent à ma conférence. Je suis Dan Allen, le créateur du project Asciidoctor. Aujourd’hui, je vais vous expliquer les bonnes pratiques pour écrire en AsciiDoc… Alors, I’ve been spending too much time practicing my French. Cette fois en anglais. My name is Dan Allen. In my business, I focus on content strategy, building communities and educating people about technology. I also lead the Asciidoctor project.
Today, I’m going to teach you how to use AsciiDoc more effectively by sharing a handful of techniques and showcasing some tools I use in my daily work. You’ll meet a muse named Asciidoctor, who will help you on your path towards attaining writing zen.
If you’re writing in AsciiDoc, you’re already following one of my recommended best practices for writing. Way to go! If not, your journey with AsciiDoc starts today. I hope when you leave here today, you’ll be ready to put these techniques and tools into practice and, plus important, take pleasure in the art of writing. In the words of Scott Chacon, author of Pro Git, you’ll be “Living the Future of Technical Documentation.”
Reflect for a moment about writing documentation. How does it make you feel?
I’m guessing many of you identify with this poor fellow. Let’s call him Jacques. Jacques feels stuck. Jacques is sufficating. Jacques feels constrained by heavy process, pigeonhole tools & erratic expectations. Jacques is writing documentation in a CMS.
If all communication made us feel this way, we’d never leave the house. In reality, it’s the opposite. We live to communicate. And we’ve done so for tens of thousands of years.
My theory is that the challenge we have with writing and maintaining technical writing is not with communication itself, but rather with the constraints we are imposing on ourselves. We are sufficiating the writing and the writer.
Think about how much you’ve communicated with each other this week. You walk up to someone and you just know what to say.
And you’re usually quite happy about it. It makes you feel good (even if sometimes a bit nervous…a good kind of nervous). Speaking in our native language comes natural to us.
It’s not confined to speaking…
How many times have you pulled out your phone to write a text message…perhaps even while speaking? You don’t give much thought to how and where you write. You just punch in (or swipe) some words and click send.
Same with e-mails. Most people are OK with writing e-mails. They don’t consider this writing. Someone asks you a question, you press reply and type away.
Think about how easy it is to tweet. The Twitter bird asks “What’s happening?”, you just fill in the blank. You’re a communication machine!
Notice that these forms of communication are responses. Très important.
Yet documentation, such as writing a README or tutorial, seems to puzzle us. We clam up and begin stressing about all sorts of things.
Pourquoi ? Writing documentation should be as simple as writing an e-mail, non ? Well, it’s complicated.
When we write documentation, all of a sudden we have to think about structure. What’s the beginning, middle and end? The prerequisites? The audience? It isn’t just question and response.
After all, we don’t go up to someone and outline what we’re going to say. (dramatization) So we’re not used to thinking about the structure, the outline. On top of that, we have to think about where and how to write.
We need to hack our, make ourselves believe we can do it. Over the years, no one has helped us believe in ourselves more than IKEA. Am I right?
-
envision goal
-
itemize tools
-
tell good from bad
-
follow the steps
-
success!
Ne stressez pas. Vous pouvez le faire.
Docs are code! To be more successful with writing and maintaining technical documentation, we need to treat it just like code. We want to introduce you to a writing system that respects documentation this way.
- AsciiDoc
-
the syntax
A plain text format for writing documentation and other technical and non-technical content
- Asciidoctor
-
the toolchain
Parser + writing and publishing tools. (50 repositories in the Asciidoctor organization on GitHub).
Free your mind by writing in the closest format to thought, plain text. Efficiently encode the information. Content in its purest form. Similar to writing on paper. Plow away the distractions. What’s most important is that you’re writing!
Fundamental requirements for running a documentation effort.
- read
-
syntax doesn’t get in the way of writing
- edit
-
can clearly see the content, even without rendering
- version
-
most critical; absolutely essential; establishes canonical source / avoids divergence; allow you to track changes; aids workflow
- share
-
ad-hoc publishing; seriously low barrier to collaboration
- convert
-
write in AsciiDoc once, publish everywhere
AsciiDoc is an input, does not dictate an output. It’s a clean separation of content and presentation. Écrire en AsciiDoc, publier partout !
Think about how you write code. You tend to put one statement on each line. Anders from the Neo4j project introduced me to the power of writing documentation using one sentence per line. This technique has single-handly transformed my writing process, and I’m eternally grateful to him. In sentence per line, you write a paragraph like you would a bulleted list, except you drop the bullets. Like HTML, endlines in paragraph content are insignficant in AsciiDoc, so this mode of writing is supported by default.
Benefits: - feels natural (matches how we write code) - localizes changes (does not cause reflow) - easier to diff - can easily rearrange sentences or disable sentences - can add commentary at the sentence level (more in a bit, will see in action in adoc-editor demo) - encourages shorter sentences (edit with a knife!) - helps you think about what you’re writing
Highly recommended.
Just like code, AsciiDoc supports line and block-level comments. This allows you to take content out of the flow either temporarily or permanently.
Once you write using sentence per line, you can use line or block comments quite effectively to try out content, swapping it in and out of place. Michael Hunger of Neo4j referred to this as “comment-driven development”
The comment feature also makes a great notation system.
The best way I’ve found to get a big picture view and also catch all the little errors while editing is to do what I call a couch read. Bring up the document on your phone and read it through. You’ll find that no mistake is too small to slip through this filter. You’ve also hacked your brain to be in the readers shoes, making a clear switch from producing to consuming. Running over to your computer takes effort, so you stick with the reading. I tend to jot down notes in a notebook while reading.
I strongly encourage you to couch read all your documents.
-
D.R.Y. = Don’t repeat yourself
-
catalog all URIs in one location
-
make it easy to update URIs when a document moves
-
don’t end up with environment-specific paths
-
also provides a way to add metadata and additional semantics to document
-
can also use attributes to create conditional content (good for publishing multiple versions of your docs)
Recommended practices: * qualify attribute names (like uri-, link-, etc) * move attributes in an include file
Primary brain hack is to write like you are answering a question. Start with an outline of questions, answer those questions, then go back and change those questions to statements in the final version.
Quick survey of some of the tools we frequently use. There is a plethora of tools available, and growing every day.
Biggest part of the tool story is AsciiDoc on GitHub. (“It all starts with GitHub”) Great for sharing content, especially in the early stages. No formal publishing workflow needed. Diff tools.
Just like with code, you use a ”fork and fix” workflow to collaboratively edit the document.
Essential for approachability is providing a clear entry point. Nothing accomplishes this like an "Edit on GitHub" button. Shows where the source is while at the same time showing how to propose a change to the file. Benefits from the lightweight GitHub Flow contribution process.
The live preview extension for Chrome & Firefox is absolutely essential. Based on Asciidoctor.js, a transpiled version of Asciidoctor that is the foundation of much of the tooling. Browse to any AsciiDoc file locally or anywhere on the internet and see a rendered version of it. (Chrome extension even features offline support)
Live preview while editing in Atom, Brackets, IntelliJ IDEA and more. In early stages of being an true IDE for writers.
Easy publishing. Focus on the content, get a beautiful result. Core value proposition of the Asciidoctor. Amazing what this does for your motivation to write.
“Google Docs for AsciiDoc” GitHub workflow is nice, but doesn’t work well for real-time edits. adoc-editor gets everyone hacking on the same version of the document, simultaneously. Everyone gets the same live preview of the document as well. This is definitely the future of writing. “Pair writing” The fact that the AsciiDoc source is just code, tools become just that, tools. And we know from programming that tools are a developers best friend. Now they can be a writers best friend too.