
Living the Future of Technical Writing - mattdeboard
https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
======
coolsunglasses
Humbly submitting the way I work on my book for learning Haskell:

[https://github.com/bitemyapp/doc-workshop](https://github.com/bitemyapp/doc-
workshop)

Uses Pandoc, compiles markdown to LaTeX, LaTeX renders to PDF.

Dynamically re-renders the preview of the PDF as I save my markdown files.

Pandoc admits inline LaTeX in the markdown documents themselves.

Auto-rebuilder script by
[http://twitter.com/mwotton](http://twitter.com/mwotton)

Learn about Pandoc here:
[http://johnmacfarlane.net/pandoc/](http://johnmacfarlane.net/pandoc/)

I edit in Emacs, but you can use whatever obviously.

~~~
jmount
Are you producing anything other than Latex/PDF from this workflow?

~~~
coolsunglasses
For now, no, but I've considered seeing if I could generate a website like
Hakyll does with Pandoc with it.

I can do anything Pandoc can do.

------
tbirdz
I haven't been able to get good quality PDF output using the docbook based
toolchain, as seems to be used in git-scribe. You can style the HTML output
with css easily, and you can even get good looking math by including your
LaTeX in a literal block, and use MathJAX in your HTML template to generate
the math when the reader looks at it.

PDF however is a different story. Currently, docbook's PDF backends use
dblatex or fop. Fop is more styleable out of the box, having many parameters
you can set. However, fop doesn't support ligatures in the output, and has
some issues with math typesetting. dblatex has better quality output, but the
amount of configurability of the xml stylesheet is limited. In order to
configure the output, you must write a LaTeX sty file, which is much more
difficult than a css stylesheet.

A nice thing about docbook is it has xml stylesheets to transform to split
page HTML and single page HTML.

Honestly though there's not really many alternatives. Texinfo can produce
single page HTML, split HTML, and PDF, but offers very little PDF styling. If
you want your output to look like a GNU Manual you are set, but even things
like changing fonts are not supported.

Troff supports PDF, but even though there are some HTML backends, they are all
pretty bad.

There are also some html-generators for LaTeX, but they aren't really that
good either.

I think there is just too much of a gap between web and paper targets to be
able to generate both in high quality from a single source. It may be
possible, but it is difficult, and current tools are not able to do this.

honestly, I would love to be wrong about this conclusion, and if anyone knows
of any other tools that can do this with good quality, please let me know.

~~~
ivanr
I built a similar single-source publishing workflow to publish my books, but
it's based around DocBook. I am very happy with DocBook because it has all the
features I need for technical publishing (styling, indexing, cross-references,
etc). For writing I use OxygenXML, which allows me to edit text without
working with XML directly and -- crucially -- supports change tracking that
makes working with editors/copyeditors a breeze.

To get good results from FOP you really need to dig deep into the XSL
stylesheets. The amount of customisation work is usually not that big, but the
problem is that you need to learn a lot about the stylesheets to know how to
make the changes. If you don't already know XSLT the learning curve can be
steep. The change-build-test process is very slow, especially when you're
essentially guessing where to make the changes. (Which, for me, happened most
of the time.)

I was happy with FOP, but eventually moved to a commercial product: 1) I
wanted to use OpenType fonts, which generally offer better quality and support
a wide range of languages, 2) full support for ligatures, 3) better handling
of SVG illustrations (FOP's integration with Batik is clunky and makes it very
difficult to use the same fonts as the main document), and 4) better indexes.

------
forsaken
This is basically the same workflow we've been building at
[https://readthedocs.org](https://readthedocs.org), but for open source
projects.

It is really an amazing workflow, and makes writing documentation as well as
books a breeze.

I would love to see a standardized site building template for asciidoctor, so
that we could support it as well as reStructuredText and Markdown.

------
ivan_ah
I really like the idea of a continuous build system, but I find the PDF
produced is not super well typeset.

If you ask me, the Future of Technical Writing looks more like this:
[https://github.com/softcover/softcover](https://github.com/softcover/softcover)
, mhartl's (markdown-->latex)-based build scripts

------
hackuser
Do these tools facilitate composition in multimedia?

I love using my text tools, including Vim and efficient markup; I would hate
to give them up. However I feel that I'm holding onto to something obsolete.
The multimedia communication future is here, and only our tools and habits are
holding us back. (My dream is that someone, even Bram Moolenaar, will write
something as efficient as Vim that incorporates multimedia as a first class,
supported format.)

People use multimedia instinctively where the tools are available, such as
SMS/MMS, social media, etc. Why do so many of our composition tools and
communication mediums still treat multimedia as a second class citizen? Why do
Word, our editors, or HN's comment system not fully incorporate multimedia?

End users and even many HN readers are accustomed to this state of affairs,
but one day text-only (or text-primary) composition will look archaic. (Yes, I
know text is more appropriate in many cases, but images/movies are more
appropriate in others and our tools stop us from using them.)

~~~
danso
Why would you think that "text-primary composition will look archaic"? What
exactly is this "social media"-form of communication are you talking about?
Because much of the social media that I see is text-based.

Just curious, but were you around during the time of MySpace's peak? That was
a site that fully integrated multimedia into profile creation and wall
posting, much more so than Facebook.

~~~
TheOtherHobbes
If you're primarily a communicator and not a coder making code for other
coders, text-primary composition already looks archaic.

Let's not forget that the main aim of PDFs and even TeX is to _replace ink on
paper._

As a goal for 2014, I'd suggest that perhaps this is lacking ambition - as is
the idea that the best of all possible systems is one where you crank a handle
on some input data to run a batch process which generates various output
formats.

>much of the social media that I see is text-based.

In my very average Facebook feed most messages include at least one image, and
as a wild hand-wavy estimate maybe 10% include a video clip.

Entire sites are devoted to slides, video tutorials, and photo sharing.

I guess if 'We only do text' works for you, that's fine. It doesn't work for a
lot of users.

As a footnote, consider that it might be possible to write software using
images, sounds, and video clips as semantic tokens instead of text strings.

There's no real reason, beyond fear of the unknown, to constrain programming
to text shuffling.

My guess is that over the next century or so, associative intelligent systems
that can parse (e.g.) visual, verbal and other sensory metaphors will provide
better tools for solving certain kinds of problems than strict Turing logic.

------
Stoo
The reasons cited here are basically why I built Storytella[0]. Writing tools
seem vastly inferior to developer tools when it comes to basic layout and
document conversion. At the moment Storytella is aimed at novels for self-
publishing authors so doesn't have much in the way of complex formatting - I
want to update the Markdown syntax it uses to include some of the extensions
available such as table formatting.

[0] [https://storytel.la/](https://storytel.la/)

------
ayrx
O'Reilly Atlas looks really interesting but the "email for a quote" thing
really puts me off.

Leanpub offers something really similar but it pretty much locks you in to
their platform to unless you want to publish through them it's not really an
option.

A self-hosting option for this type of software, open source or not, will be
really nice.

------
redthrow
Mark Pilgrim wrote "Dive into HTML5" in HTML and he (his publisher) also
published the paper edition. Maybe you don't need all the tools.

[http://diveintohtml5.info/](http://diveintohtml5.info/)

------
protonfish
I am sure the future of writing looks something like this, (first technical,
then all) but it can't happen fast enough for me. I am stuck with Word on my
current project but I am planning to write early drafts in Markdown and
convert.

------
MoOmer
Thank you for your work. Pro Git is the Git Bible; looking forward to reading
v2.

------
keypusher
This makes a lot of sense.

