<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
  <id>https://www.ericholscher.com</id>
  <title>Eric Holscher - Posts in documentation</title>
  <updated>2026-11-12T13:36:31.340583+00:00</updated>
  <link href="https://www.ericholscher.com"/>
  <link href="https://www.ericholscher.com/blog/archive/category/documentation/atom.xml" rel="self"/>
  <generator uri="https://ablog.readthedocs.io/" version="0.11.13">ABlog</generator>
  <entry>
    <id>https://www.ericholscher.com/blog/2018/feb/7/the-post-i-never-published/</id>
    <title>The post I never published</title>
    <updated>2018-02-07T00:00:00+00:00</updated>
    <content type="html">&lt;section id="the-post-i-never-published"&gt;

&lt;p&gt;Looking back,
the file was created on my 29th birthday:&lt;/p&gt;
&lt;div class="highlight-none notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;Jul  9  2016 read-the-docs-sucession-planning.rst
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;I had failed. I burned out. &lt;em&gt;(I’m fine now, don’t worry!)&lt;/em&gt;&lt;/p&gt;
&lt;p&gt;I started writing a blog post that you’ve seen around the internet time and time again.
Another creator of another open source project steps down,
offers the project to anyone who will actually help maintain the thing.
Maybe someone steps up,
maybe not..&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;Is this the &lt;em&gt;only&lt;/em&gt; way to get people to actually contribute to my project?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Is it &lt;em&gt;blackmail&lt;/em&gt;?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;How does using &lt;em&gt;the nuclear option&lt;/em&gt; affect my career?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;em&gt;What will people think&lt;/em&gt;?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Am I &lt;em&gt;really&lt;/em&gt; a failure?&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;I could have done &lt;em&gt;more&lt;/em&gt;&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;section id="the-post"&gt;
&lt;h2&gt;The post&lt;/h2&gt;
&lt;p&gt;I actually forgot that I had written it,
until looking back in my drafts for ideas of new posts to write.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;This post is a first draft,
written in July 2016,
and was never finished.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;I’m sharing it because I think it’s important to talk about these things,
and mental health is not something we talk about enough.
I’m doing well now,
which makes it easier to talk about.&lt;/p&gt;
&lt;div class="highlight-rst notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="gh"&gt;Read the Docs Succession Planning&lt;/span&gt;
&lt;span class="gh"&gt;=================================&lt;/span&gt;

I've been working on Read the Docs for almost 6 years now.
It's a large part of my professional identity,
the thing that I'm the most known for.
I've always thought I would be happy to work on it forever.
However,
the leaves change color,
the world spins,
and I get older.

At this point,
I have started to feel jaded and less inspired.
I see the problems easier than new solutions,
and don't have the vigor of youth and possibility.
I still firmly believe that the project can do more good in the world,
but I become less convinced that I'm the one to do it over the long term.

Sadly,
I've been failing at growing a community of contributors around the project.
I don't fully understand why that is,
but it's something that I've become more worried about over time.
I don't necessarily have the energy to onboard new people like I used to,
and I want to make sure the project is in good hands for the long term.

So,
this letter is a public recognition of this failing,
and hopefully will also spur action on the part of some kind soul.

Read the Docs needs more people who are willing to work on it.
We need people to do just about everything in the project:

&lt;span class="m"&gt;*&lt;/span&gt; Translation management
&lt;span class="m"&gt;*&lt;/span&gt; Operations and Infrastructure work
&lt;span class="m"&gt;*&lt;/span&gt; Documentation updates and improvements
&lt;span class="m"&gt;*&lt;/span&gt; Support and GitHub ticket triage
&lt;span class="m"&gt;*&lt;/span&gt; Design and UX updates and improvements
&lt;span class="m"&gt;*&lt;/span&gt; Development of new features and new ideas
&lt;span class="m"&gt;*&lt;/span&gt; Promotion of the project with blogging and social media

Just about anything that someone could be needed is needed.
We've had a lack of interest in development on the project for a long time,
and as such things have languished.

&lt;span class="gh"&gt;Get Involved&lt;/span&gt;
&lt;span class="gh"&gt;------------&lt;/span&gt;

We have a well-documented process for getting involved in the tickets:

&lt;span class="m"&gt;*&lt;/span&gt; http://docs.readthedocs.io/en/latest/contribute.html

We also have hundreds of possible projects that can be done from the operations and development side.
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;&lt;em&gt;That’s all that I managed to write.&lt;/em&gt;&lt;/p&gt;
&lt;/section&gt;
&lt;section id="now"&gt;
&lt;h2&gt;Now&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Things are better now.&lt;/strong&gt;
I don’t recognize the person who wrote that post.
They seem distant,
a faint memory.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Read the Docs is sustainable.&lt;/strong&gt;
As of January 2018,
we have a team of four people paid to work on the project.
It feels like we might still nudge the world.
I feel like I could keep working on this project for a long time.&lt;/p&gt;
&lt;p&gt;I got really close to quitting the project though.
It was really hard.
I struggled for a long time.
For every person who &lt;em&gt;goes nuclear&lt;/em&gt;,
there are 10 who have gotten close.
I’m glad that things worked out okay for me,
but not everyone is so lucky.&lt;/p&gt;
&lt;p&gt;I hope we can take some &lt;a class="reference external" href="http://ericholscher.com/blog/2016/aug/31/funding-oss-marketing-money/"&gt;lessons&lt;/a&gt; from Read the Docs and apply them more broadly.
I hope the &lt;a class="reference external" href="https://changelog.com/rfc"&gt;work&lt;/a&gt; others are doing in this area makes it better.
There are a lot of problems that I still don’t know the answer to.&lt;/p&gt;
&lt;p&gt;There’s still a lot more work to do.&lt;/p&gt;
&lt;/section&gt;
&lt;/section&gt;
</content>
    <link href="https://www.ericholscher.com/blog/2018/feb/7/the-post-i-never-published/"/>
    <summary>Looking back,
the file was created on my 29th birthday:</summary>
    <category term="burnout" label="burnout"/>
    <category term="opensource" label="open source"/>
    <category term="python" label="python"/>
    <category term="sustain" label="sustain"/>
    <category term="sustainability" label="sustainability"/>
    <category term="vulnerability" label="vulnerability"/>
    <published>2018-02-07T00:00:00+00:00</published>
  </entry>
  <entry>
    <id>https://www.ericholscher.com/blog/2017/feb/13/docs-are-json-for-the-brain/</id>
    <title>Documentation is JSON for the Brain</title>
    <updated>2017-02-13T00:00:00+00:00</updated>
    <content type="html">&lt;section id="documentation-is-json-for-the-brain"&gt;

&lt;p&gt;When you are writing software,
you build a mental model of the program in your brain.
This is how you make decisions and reason about how the program might work,
how data flows,
or what designs make the most sense.&lt;/p&gt;
&lt;p&gt;A large amount of the time spent “programming” is actually building a mental model in your brain.
You spend time understanding &lt;em&gt;how&lt;/em&gt; and &lt;em&gt;why&lt;/em&gt; things are put together.
Programmers often talk about how interruptions can stop them from being productive for 15-30 minutes afterwards.
This is because they are losing the mental model that they have spent time building.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Reading documentation is the quickest way to load mental state into your brain.&lt;/strong&gt;
It gives you a shortcut,
faster than reading code,
to understand what the code is doing,
and why.
Writing documentation is the best way to preserve the mental model in your mind,
and turn it into written words for later.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Documentation is JSON for your mental state.&lt;/strong&gt;
You should write docs so that whoever is maintaining your code will be able to get up to speed quickly,
and understand why certain decisions were made.
That person might even be you in 6 months.&lt;/p&gt;
&lt;/section&gt;
</content>
    <link href="https://www.ericholscher.com/blog/2017/feb/13/docs-are-json-for-the-brain/"/>
    <summary>When you are writing software,
you build a mental model of the program in your brain.
This is how you make decisions and reason about how the program might work,
how data flows,
or what designs make the most sense.</summary>
    <category term="analogy" label="analogy"/>
    <category term="brain" label="brain"/>
    <category term="docs" label="docs"/>
    <category term="json" label="json"/>
    <category term="python" label="python"/>
    <published>2017-02-13T00:00:00+00:00</published>
  </entry>
  <entry>
    <id>https://www.ericholscher.com/blog/2016/oct/6/authoring-documentation-with-semantic-meaning/</id>
    <title>Semantic Meaning in Authoring Documentation</title>
    <updated>2016-10-06T00:00:00+00:00</updated>
    <content type="html">&lt;section id="semantic-meaning-in-authoring-documentation"&gt;
&lt;span id="semantic-meaning"&gt;&lt;/span&gt;
&lt;p&gt;Semantic Meaning in documentation is the separation of what something is from what it looks like.
What we &lt;em&gt;mean&lt;/em&gt; and what we &lt;em&gt;display&lt;/em&gt; are very different things.&lt;/p&gt;
&lt;p&gt;We might want to warn someone in our writing,
but we don’t want to think about how to display this.
Writing with Semantic Meaning gives us this power.&lt;/p&gt;
&lt;section id="semantics"&gt;
&lt;h2&gt;Semantics&lt;/h2&gt;
&lt;p&gt;As an example,
if we were writing documentation in HTML,
we could warn a user with bold:&lt;/p&gt;
&lt;div class="highlight-html notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;b&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
    Don't do this, it will break your system!
&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;b&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;This has no semantics.
&lt;em&gt;Bold doesn’t mean “warning”,
it is simply a way of displaying text.&lt;/em&gt;
A better example in HTML is:&lt;/p&gt;
&lt;div class="highlight-html notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;span&lt;/span&gt; &lt;span class="na"&gt;class&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"warning"&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
    Don't do this, it will break your system!
&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;span&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;This allows you to write &lt;em&gt;what&lt;/em&gt; something is,
but not have to worry about what it looks like.
Your designer might decide that warnings should be bold and red:&lt;/p&gt;
&lt;div class="highlight-css notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;warning&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
&lt;span class="w"&gt;    &lt;/span&gt;&lt;span class="n"&gt;text-format&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;bold&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="w"&gt;    &lt;/span&gt;&lt;span class="k"&gt;color&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;red&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;The important part is that you don’t need to think about what warnings look like,
just that it’s a warning.&lt;/p&gt;
&lt;p&gt;To go one step further,
in &lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/rest.html"&gt;reStructuredText&lt;/a&gt; we can do:&lt;/p&gt;
&lt;div class="highlight-rst notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="p"&gt;..&lt;/span&gt; &lt;span class="ow"&gt;warning&lt;/span&gt;&lt;span class="p"&gt;::&lt;/span&gt; Don't do this, it will break your system!
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;Then &lt;a class="reference external" href="http://www.sphinx-doc.org"&gt;Sphinx&lt;/a&gt; or some other tool will generate the proper HTML or PDF with styles for us.
reStructuredText is abstracted away from all of the output formats,
so you write in one format,
and it transforms it properly into HTML,
PDF,
XML,
or any other format it supports.&lt;/p&gt;
&lt;p&gt;This approach allows your designers to work with a systematic and standardized set of class names,
generated from the tooling.
This keeps all your styles the same,
and allows the tool to warn you if you try and represent something that doesn’t exist.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="value-of-semantic-documentation"&gt;
&lt;h2&gt;Value of Semantic Documentation&lt;/h2&gt;
&lt;p&gt;When you write documentation,
you form a mental model in your head of the document you’re writing.
When you use a powerful tool like reStructuredText,
you can &lt;em&gt;think&lt;/em&gt; in terms of &lt;em&gt;warnings&lt;/em&gt;,
&lt;em&gt;references&lt;/em&gt;,
&lt;em&gt;classes&lt;/em&gt;,
&lt;em&gt;objects&lt;/em&gt;,
and other powerful semantic constructs.&lt;/p&gt;
&lt;p&gt;You start thinking in terms of &lt;em&gt;nouns&lt;/em&gt; that can be represented in your problem domain.
You can then encode this model into your document:&lt;/p&gt;
&lt;div class="highlight-rst notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="p"&gt;..&lt;/span&gt; &lt;span class="ow"&gt;warning&lt;/span&gt;&lt;span class="p"&gt;::&lt;/span&gt; Make sure you &lt;span class="na"&gt;:term:&lt;/span&gt;&lt;span class="nv"&gt;`instantiate`&lt;/span&gt;
             the Response objects before you use it.

You can read more about the &lt;span class="na"&gt;:cls:&lt;/span&gt;&lt;span class="nv"&gt;`django.http.Response`&lt;/span&gt;
in our &lt;span class="na"&gt;:doc:&lt;/span&gt;&lt;span class="nv"&gt;`/api/response`&lt;/span&gt; page.
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;In the above section,
I thought &lt;em&gt;Hey, maybe someone doesn’t know what instantiate means.&lt;/em&gt;
I was able to link to the glossary with &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;:term:&lt;/span&gt;&lt;/code&gt;.
I didn’t have to look up the URL for our glossary and link to that.
I didn’t have to think about how to style glossary references.
&lt;strong&gt;I was able to simply write what I meant,
and move on.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;When you write with semantics,
you can encode more of your mental state into the words you write.
Conversely,
if you write without semantics,
valuable information about your writing is lost.&lt;/p&gt;
&lt;p&gt;Semantic information also acts as a type of documentation for our writing.
Similar to &lt;a class="reference external" href="https://en.wikipedia.org/wiki/Type_system"&gt;type systems&lt;/a&gt; in programming,
they allow you to be explicit about what you’re talking about.
When you write documentation about a &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;Response&lt;/span&gt;&lt;/code&gt; object,
it isn’t immediately obvious &lt;em&gt;what&lt;/em&gt; that is.
When you write about a &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;:cls:`django.http.Response`&lt;/span&gt;&lt;/code&gt;,
it is explicitly defined what you’re talking about.&lt;/p&gt;
&lt;div class="admonition note"&gt;
&lt;p class="admonition-title"&gt;Note&lt;/p&gt;
&lt;p&gt;When you write documentation in Markdown,
there is no clear way to represent semantic information.
You can make something &lt;em&gt;bold&lt;/em&gt;,
but you can’t make something a &lt;em&gt;warning&lt;/em&gt;.&lt;/p&gt;
&lt;p&gt;Please &lt;a class="reference internal" href="../../../2016/mar/15/dont-use-markdown-for-technical-docs/"&gt;&lt;span class="doc"&gt;don’t write documentation in Markdown&lt;/span&gt;&lt;/a&gt;.&lt;/p&gt;
&lt;/div&gt;
&lt;/section&gt;
&lt;section id="conclusion"&gt;
&lt;h2&gt;Conclusion&lt;/h2&gt;
&lt;p&gt;Communicating with words is a much different skill than transferring communicating with design.
In the process of producing documentation however,
they are two sides of the same coin.
We have to both write and display information for users,
and make it easy for them to understand it.&lt;/p&gt;
&lt;p&gt;As an author,
you should only need to care about communicating knowledge with words.
Writing with semantic meaning allows you to properly seperate communcation with words and design.&lt;/p&gt;
&lt;p&gt;You should write in a format that gives you the most semantic meaning possible.
This:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;Allows you to focus on communicating information, not thinking about what HTML class you need for a concept&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Expand your own ability to think about your writing in terms of semantic nouns, allowing you to better structure your thoughts&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Allows tooling to raise errors when you try to reference semantic concepts that doesn’t exist (typos, etc.)&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Give people updating your documents explicit information about what you’re documenting&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Allows your documentation systems to crosslink information and provide a better experience for your user&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Allows your designer to apply consistent styles to all types of information&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;When you have the ability to write with powerful semantic constructs,
writing becomes easier and more powerful.
If you want to be the most efficient and useful writer,
you write in a way that preserves the most of your mental model while writing.
You write with a tool that gives you semantic meaning.&lt;/p&gt;
&lt;/section&gt;
&lt;/section&gt;
</content>
    <link href="https://www.ericholscher.com/blog/2016/oct/6/authoring-documentation-with-semantic-meaning/"/>
    <summary>Semantic Meaning in documentation is the separation of what something is from what it looks like.
What we mean and what we display are very different things.</summary>
    <category term="markdown" label="markdown"/>
    <category term="python" label="python"/>
    <category term="reStructuredText" label="reStructuredText"/>
    <category term="semanticmeaning" label="semantic meaning"/>
    <category term="semantics" label="semantics"/>
    <published>2016-10-06T00:00:00+00:00</published>
  </entry>
  <entry>
    <id>https://www.ericholscher.com/blog/2016/sep/23/documentation-as-json/</id>
    <title>A Selfish Appeal for Documentation</title>
    <updated>2016-09-24T00:00:00+00:00</updated>
    <content type="html">&lt;section id="a-selfish-appeal-for-documentation"&gt;

&lt;p&gt;Writing code is the act of building a mental model of a problem,
and then translating that model into executable software.&lt;/p&gt;
&lt;p&gt;Writing documentation about software is the act of serializing this mental state.
&lt;strong&gt;You can think about documentation as JSON for your mental state while programming.&lt;/strong&gt;
Documentation allows you to dump the information in your brain,
in a format that allows others to reload into theirs.&lt;/p&gt;
&lt;p&gt;Reading source code is the most inefficient way of transferring mental state.
It also only conveys information on &lt;em&gt;what&lt;/em&gt; the code does,
not &lt;em&gt;why&lt;/em&gt; it does it.
My favorite rule around code comments fits well here:&lt;/p&gt;
&lt;blockquote&gt;
&lt;div&gt;&lt;p&gt;Document the why, not the how&lt;/p&gt;
&lt;/div&gt;&lt;/blockquote&gt;
&lt;p&gt;By writing documentation,
you are able to load the &lt;em&gt;why&lt;/em&gt; of your code into someone elses brain.
Or reload it back into your brain 6 months after you wrote it.
This allows you to complete your job faster,
and also stops you from making the same mistakes over again.&lt;/p&gt;
&lt;p&gt;Do yourself a favor and write documentation for your software.&lt;/p&gt;
&lt;/section&gt;
</content>
    <link href="https://www.ericholscher.com/blog/2016/sep/23/documentation-as-json/"/>
    <summary>Writing code is the act of building a mental model of a problem,
and then translating that model into executable software.</summary>
    <category term="docs" label="docs"/>
    <category term="tips" label="tips"/>
    <category term="whynothow" label="why not how"/>
    <published>2016-09-24T00:00:00+00:00</published>
  </entry>
  <entry>
    <id>https://www.ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/</id>
    <title>The Power of Sphinx: Integrating Jinja with RST</title>
    <updated>2016-07-25T09:00:00+00:00</updated>
    <content type="html">&lt;section id="the-power-of-sphinx-integrating-jinja-with-rst"&gt;

&lt;p&gt;&lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/"&gt;Sphinx&lt;/a&gt; is a super powerful tool.
This has its upsides and downsides.
One of the major downsides is that historically it has been built as a framework that allows users to do just about anything.
This is great,
except it also means that a lot of the specific value out of the modular design hasn’t been documented or made explicit to users.
I’m hoping to address some of this power in a set of blog posts.&lt;/p&gt;
&lt;p&gt;Today I’ll cover integrating the templating language &lt;a class="reference external" href="http://jinja.pocoo.org/docs/dev/templates/"&gt;Jinja&lt;/a&gt; inside your RST files.
This is a really useful thing,
and allows a large number of powerful display semantics inside of your RST files.&lt;/p&gt;
&lt;p&gt;Jinja is also the templating engine that Sphinx uses internally for rendering HTML.
This means you already have the library installed with Sphinx,
so no external dependency is required.&lt;/p&gt;
&lt;section id="the-extension"&gt;
&lt;h2&gt;The Extension&lt;/h2&gt;
&lt;p&gt;Most of the power of Sphinx comes from the ability to plug into any part of the documentation building process.
Sphinx has an exhaustive list of &lt;a class="reference external" href="https://www.sphinx-doc.org/en/master/extdev/event_callbacks.html"&gt;Sphinx events&lt;/a&gt;,
which I recommend reading up on.
This extension will use the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;source-read&lt;/span&gt;&lt;/code&gt; hook,
which fires when the actual RST file is read from the disk.&lt;/p&gt;
&lt;p&gt;From there it is the simple matter of taking the source that has been read,
and passing it through Jinja.
Here is the full extension:&lt;/p&gt;
&lt;div class="highlight-python notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="k"&gt;def&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nf"&gt;rstjinja&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;docname&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;source&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt;
&lt;span class="w"&gt;    &lt;/span&gt;&lt;span class="sd"&gt;"""&lt;/span&gt;
&lt;span class="sd"&gt;    Render our pages as a jinja template for fancy templating goodness.&lt;/span&gt;
&lt;span class="sd"&gt;    """&lt;/span&gt;
    &lt;span class="c1"&gt;# Make sure we're outputting HTML&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;format&lt;/span&gt; &lt;span class="o"&gt;!=&lt;/span&gt; &lt;span class="s1"&gt;'html'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt;
    &lt;span class="n"&gt;src&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;source&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="n"&gt;rendered&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;templates&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;render_string&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="n"&gt;src&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;config&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;html_context&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;source&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;rendered&lt;/span&gt;

&lt;span class="k"&gt;def&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nf"&gt;setup&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt;
    &lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;connect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"source-read"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;rstjinja&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;This simple extension gives us a ton of power.
Let’s talk through one example.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="generating-docs-from-data"&gt;
&lt;h2&gt;Generating Docs from Data&lt;/h2&gt;
&lt;p&gt;A lot of times we have an external data set that we want to generate into our documentation.
Let’s say this is a list of team members that is maintained in a remote system,
and we want to include in our docs.
If we can get that data into JSON,
it’s pretty simple to add it into our project.&lt;/p&gt;
&lt;p&gt;In our &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;conf.py&lt;/span&gt;&lt;/code&gt;,
or another Sphinx extension,
we can do:&lt;/p&gt;
&lt;div class="highlight-python notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="kn"&gt;import&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nn"&gt;json&lt;/span&gt;

&lt;span class="n"&gt;staff&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;json&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;load&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;file&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'data/company-staff.json'&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;

&lt;span class="n"&gt;html_context&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="s1"&gt;'company_staff'&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;staff&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;This gives us the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;company_staff&lt;/span&gt;&lt;/code&gt; variable in our HTML context,
which will be availabe from Jinja.
Then we can generate our &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;staff.rst&lt;/span&gt;&lt;/code&gt; file:&lt;/p&gt;
&lt;div class="highlight-rst notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="gh"&gt;Staff&lt;/span&gt;
&lt;span class="gh"&gt;=====&lt;/span&gt;

{% for member in company_staff %}
{% if member.is_active %}
&lt;span class="m"&gt;*&lt;/span&gt; &lt;span class="s"&gt;`{{ member.name }} &lt;/span&gt;&lt;span class="si"&gt;&amp;lt;{{ member.url }}&amp;gt;&lt;/span&gt;&lt;span class="s"&gt;`_&lt;/span&gt;
{% else %}
&lt;span class="m"&gt;*&lt;/span&gt; {{ member.name }} (Emeritus)
{% endif %}
{% endfor %}
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;div class="admonition note"&gt;
&lt;p class="admonition-title"&gt;Note&lt;/p&gt;
&lt;p&gt;The Jinja templates will be rendered &lt;em&gt;before&lt;/em&gt; the RST is processed.&lt;/p&gt;
&lt;/div&gt;
&lt;p&gt;Allowing ourselves to use Jinja inside of RST gives us a whole set of logic that isn’t available in the RST language itself.&lt;/p&gt;
&lt;p&gt;This approach is incredibly powerful,
but please make sure you don’t overdo it!
Try to keep the Jinja logic simple,
and only apply it to things that alter the display of the page.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="want-more-tips"&gt;
&lt;h2&gt;Want more tips?&lt;/h2&gt;
&lt;p&gt;I love talking and thinking about the power of Sphinx.
Along with blogging,
I provide Sphinx documentation training for companies.
We do half-day, full-day, and multi-day classes.
Shoot me an &lt;a class="reference external" href="mailto:training&amp;#37;&amp;#52;&amp;#48;readthedocs&amp;#46;com"&gt;email&lt;/a&gt; or check out our &lt;a class="reference external" href="http://www.sphinxtraining.com"&gt;sphinx training website&lt;/a&gt; for more info.&lt;/p&gt;
&lt;/section&gt;
&lt;/section&gt;
</content>
    <link href="https://www.ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/"/>
    <summary>Sphinx is a super powerful tool.
This has its upsides and downsides.
One of the major downsides is that historically it has been built as a framework that allows users to do just about anything.
This is great,
except it also means that a lot of the specific value out of the modular design hasn’t been documented or made explicit to users.
I’m hoping to address some of this power in a set of blog posts.</summary>
    <category term="jinja" label="jinja"/>
    <category term="sphinx" label="sphinx"/>
    <category term="training" label="training"/>
    <published>2016-07-25T09:00:00+00:00</published>
  </entry>
  <entry>
    <id>https://www.ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/</id>
    <title>An introduction to Sphinx and Read the Docs for Technical Writers</title>
    <updated>2016-07-01T00:00:00+00:00</updated>
    <content type="html">&lt;section id="an-introduction-to-sphinx-and-read-the-docs-for-technical-writers"&gt;

&lt;p&gt;Treating documentation as code is becoming a major theme in the software industry.
This is coming from both sides,
with developers starting to treat documentation as a priority alongside tests and code,
and writers seeing a lot of value in integrating more into the development process.
This marrying of cultures isn’t simple,
but having the proper tools for the job makes both sides happy with the process and the results that get produced.&lt;/p&gt;
&lt;p&gt;A lot of developer tools don’t work well for writers.
Sphinx and Read the Docs are unique in this ecosystem,
in that they have powerful features that both writers and developers want,
in one convenient package.&lt;/p&gt;
&lt;section id="overview-of-the-ecosystem"&gt;
&lt;h2&gt;Overview of the Ecosystem&lt;/h2&gt;
&lt;p&gt;Read the Docs is the largest open source documentation hosting site in the world.
Open Source in this context means both that the code is open source,
and the documentation hosted is for open source software.
It is a developer focused platform,
but it has most of the features that technical writers have come to expect in a tool as well.
This blending of worlds makes it the best suited platform for teams that want both writers and developers contributing to product and API documentation.&lt;/p&gt;
&lt;p&gt;Read the Docs is best thought of as a continuous documentation platform for Sphinx.
Continuous documentation is analogous to continuous integration of code,
which runs the tests on each commit.
In practice it means that your documentation is built,
tested,
and updated on every commit.&lt;/p&gt;
&lt;p&gt;Sphinx provides a documentation generator that is best-in-class for software docs.
Sphinx documents are written in the reStructuredText markup language.
reStructuredText is similar to Markdown,
but much more powerful,
as you’ll see in this article.
Read the Docs provides a hosting platform for Sphinx,
running a build on each commit of your repository.&lt;/p&gt;
&lt;p&gt;As a writer who uses Sphinx,
your day to day is writing reStructuredText in plain text files.
You then build your documentation by running Sphinx on the command line.
Generally it’s easiest to output HTML for local writing and testing,
and then you can let Read the Docs generate PDF’s and other formats.&lt;/p&gt;
&lt;p&gt;This article provides an overview of the features of Sphinx and Read the Docs,
and enables you to evaluate them for use in your organization.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="introduction-to-sphinx"&gt;
&lt;h2&gt;Introduction to Sphinx&lt;/h2&gt;
&lt;p&gt;&lt;a class="reference external" href="http://www.sphinx-doc.org/"&gt;Sphinx&lt;/a&gt; is the documentation tool of choice for the Python language community,
and increasingly also for other programming languages and tools.
It was &lt;a class="reference external" href="https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)"&gt;originally created&lt;/a&gt; in 2008 to document the Python language itself.&lt;/p&gt;
&lt;p&gt;Over the past eight years,
it has turned into a robust and mature solution for software documentation.
It includes a number of features that writers expect,
such as:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;dl class="simple"&gt;
&lt;dt&gt;Single Source Publishing&lt;/dt&gt;&lt;dd&gt;&lt;ul&gt;
&lt;li&gt;&lt;p&gt;Output HTML, PDF, ePub, and more&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Content reuse through includes&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Conditional includes based on content type and tags&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/dd&gt;
&lt;/dl&gt;
&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Multiple mature HTML themes that provide great user experience on mobile and desktop&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Referencing across pages, documents, and projects&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Index and Glossary support&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Internationalization support&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;It also has practical and powerful tools for documenting software specifically,
including:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;Semantic referencing of software concepts, including classes, functions, programs, variables, etc.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Including code comments in documentation output for many programming languages&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Tools for documenting HTTP APIs&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Extensions with the Python language&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;A vast array of third party extensions providing powerful new roles and directives&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This article isn’t large enough to cover all of the power packed into this tool.
But I hope to show enough to pique reader interest so that you can try these tools out and research their capacity for yourself.&lt;/p&gt;
&lt;section id="using-sphinx"&gt;
&lt;h3&gt;Using Sphinx&lt;/h3&gt;
&lt;p&gt;reStructuredText is a powerful language primarily because the syntax can be extended.
reStructuredText supports two types of extension:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;Paragraph level (with Directives)&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Inline level (with Interpreted Text Roles, or roles for short)&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;section id="paragraph-level-markup"&gt;
&lt;h4&gt;Paragraph Level Markup&lt;/h4&gt;
&lt;p&gt;Let’s see a basic example of a &lt;em&gt;Directive&lt;/em&gt; in reStructuredText:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;.. warning:: Here be dragons! This topic covers a number of options that
   might alter your database.

   Proceed with caution!

.. figure:: screenshot-control-panel.jpg
   :width: 50%

   An overview of the admin control panel.
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;Here &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;warning&lt;/span&gt;&lt;/code&gt; acts as the name of the directive,
and is the part you can extend for custom directives.
In the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;figure&lt;/span&gt;&lt;/code&gt;,
&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;screenshot-control-panel.jpg&lt;/span&gt;&lt;/code&gt; is an &lt;em&gt;argument&lt;/em&gt;,
&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;:width:&lt;/span&gt;&lt;/code&gt; is an &lt;em&gt;option&lt;/em&gt;,
and the rest is the &lt;em&gt;content&lt;/em&gt;
They enable customization of directives,
and show the full power of reStructuredText.&lt;/p&gt;
&lt;div class="admonition note"&gt;
&lt;p class="admonition-title"&gt;Note&lt;/p&gt;
&lt;p&gt;You’ll notice that Sphinx uses whitespace to denote where a directive ends.
The “Proceed with caution!” is still part of the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;warning&lt;/span&gt;&lt;/code&gt;,
and everything that continues to be indented will be part of that warning.&lt;/p&gt;
&lt;/div&gt;
&lt;p&gt;Sphinx ships with a number of powerful directives for documenting code.
You can also write your own if you have someone on your team that knows Python.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="inline-markup"&gt;
&lt;h4&gt;Inline Markup&lt;/h4&gt;
&lt;p&gt;For extensibility inside of a paragraph Sphinx uses roles.
Here is an example:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;You can learn more about this in :rfc:`1984`.
It is implemented in our code at :class:`System.Security`
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;Here you can see &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;rfc&lt;/span&gt;&lt;/code&gt; and &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;class&lt;/span&gt;&lt;/code&gt; act as the name of the role,
and then you can pass in a single argument.
For the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;rfc&lt;/span&gt;&lt;/code&gt; role,
it generates a link to the online reference for RFC 1984 with a text of &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;RFC&lt;/span&gt; &lt;span class="pre"&gt;1984&lt;/span&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;class&lt;/span&gt;&lt;/code&gt; role is where things get interesting.
This acts as a reference to the class &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;System.Security&lt;/span&gt;&lt;/code&gt; that is documented in your project,
which is a hyperlink in the HTML output,
but also a working link in PDF and other outputs as well.&lt;/p&gt;
&lt;p&gt;You can implement your own roles with Python.
This enables you to create powerful semantic constructs inside the actual &lt;em&gt;markup&lt;/em&gt; you’re using to write documentation.
If you worked building software at a toy factory,
you can create a custom semantic sytnax for our own software:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;Check out :jira:`199` for information on the :toy:`jump-rope`.
There is a fix in our :unit-test:`assert-jump-rope-length`.
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;These custom roles work in your &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;.rst&lt;/span&gt;&lt;/code&gt; files,
but also in any kind content that is pulled out of a comment in your source code too.&lt;/p&gt;
&lt;p&gt;Now,
let’s see how you take these sets of reStructuredText files and turn them into a document set.&lt;/p&gt;
&lt;/section&gt;
&lt;/section&gt;
&lt;/section&gt;
&lt;section id="table-of-contents-tree"&gt;
&lt;h2&gt;Table of Contents Tree&lt;/h2&gt;
&lt;p&gt;Sphinx lets you combine multiple pages into a cohesive hierarchy.
The &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;toctree&lt;/span&gt;&lt;/code&gt; directive is a fundamental part of this structure.&lt;/p&gt;
&lt;div class="highlight-rst notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="p"&gt;..&lt;/span&gt; &lt;span class="ow"&gt;toctree&lt;/span&gt;&lt;span class="p"&gt;::&lt;/span&gt;
   &lt;span class="nc"&gt;:maxdepth:&lt;/span&gt; 2

   install
   support
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;The above example outputs a Table of Contents in the page where it occurs.
The &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;maxdepth&lt;/span&gt;&lt;/code&gt; argument tells Sphinx to include 2 levels of headers.
This also tells Sphinx that the other pages are sub-pages of the current page,
creating a “tree” structure of the pages:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;index
├── install
├── support
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;The TOC Tree is also used for generating the global navigation inside of Sphinx.
The &lt;cite&gt;index&lt;/cite&gt; at the top of your project acts as the root of the navigation.
The &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;toctree&lt;/span&gt;&lt;/code&gt; is quite important,
and one of the most powerful concepts in Sphinx.&lt;/p&gt;
&lt;p&gt;More info on the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;toctree&lt;/span&gt;&lt;/code&gt; can be found here:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;&lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/markup/toctree.html"&gt;http://www.sphinx-doc.org/en/stable/markup/toctree.html&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/section&gt;
&lt;section id="working-with-code"&gt;
&lt;h2&gt;Working with Code&lt;/h2&gt;
&lt;p&gt;Showing code examples is a common task in all documentation.
Sphinx is quite well prepared for this task.
Let’s see how we can show a basic code example:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="o"&gt;..&lt;/span&gt; &lt;span class="n"&gt;code&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;block&lt;/span&gt;&lt;span class="p"&gt;::&lt;/span&gt; &lt;span class="n"&gt;python&lt;/span&gt;
   &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;linenos&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;

   &lt;span class="kn"&gt;import&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nn"&gt;antigravity&lt;/span&gt;

   &lt;span class="k"&gt;def&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nf"&gt;main&lt;/span&gt;&lt;span class="p"&gt;():&lt;/span&gt;
       &lt;span class="n"&gt;antigravity&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;fly&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;This markup displays the Python snippet with syntax highlighting and line numbers.
The &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;python&lt;/span&gt;&lt;/code&gt; in the above example is an argument to the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;code-block&lt;/span&gt;&lt;/code&gt; &lt;em&gt;directive&lt;/em&gt;.
The &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;:linesnos:&lt;/span&gt;&lt;/code&gt; is an &lt;em&gt;option&lt;/em&gt; that says to display line numbers for the code block.
In the HTML output,
it would look like this:&lt;/p&gt;
&lt;img alt="https://www.ericholscher.com/_images/code.png" src="https://www.ericholscher.com/_images/code.png" /&gt;
&lt;p&gt;Sphinx doesn’t stop there though.
It allows you to store your code examples in external files,
and be included in your documentation for easier maintenance.
This uses the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;literalinclude&lt;/span&gt;&lt;/code&gt; directive:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="o"&gt;..&lt;/span&gt; &lt;span class="n"&gt;literalinclude&lt;/span&gt;&lt;span class="p"&gt;::&lt;/span&gt; &lt;span class="n"&gt;example&lt;/span&gt;&lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;rb&lt;/span&gt;
   &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;language&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;ruby&lt;/span&gt;
   &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;emphasize&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;lines&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;12&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="mi"&gt;15&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;18&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;The neat addition here is the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;:emphasize-lines:&lt;/span&gt;&lt;/code&gt;.
This shows the lines highlighted in your output.
This is quite useful for showing sets of code examples where a subset of the code changes.
You can also specify just a subset of lines to show with the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;:lines:&lt;/span&gt;&lt;/code&gt; option,
so you don’t have to manage multiple snippets.&lt;/p&gt;
&lt;p&gt;There’s far more power to Sphinx directives than this article can show.
You can see the full documentation for them on the Sphinx website:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;&lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/markup/code.html"&gt;http://www.sphinx-doc.org/en/stable/markup/code.html&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/section&gt;
&lt;section id="working-with-references"&gt;
&lt;h2&gt;Working with References&lt;/h2&gt;
&lt;p&gt;A powerful reference system is a large part of the power of Sphinx.
You are able to reference arbitrary headings and paragraphs in your content,
but also semantically reference a large number of programming concepts as well.
On top of that,
Sphinx includes &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;intersphinx&lt;/span&gt;&lt;/code&gt; which allows referencing across Sphinx projects.
This means that if you have multiple projects inside your company,
you can still use semantic referencing across them!&lt;/p&gt;
&lt;p&gt;A simple reference is defined like this:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;.. _reference-target-name::

This is a bit of content.

This is how you point to the above reference, :ref:`reference-target-name`
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;Sphinx also includes a number of other semantic reference types.
Examples of other semantic reference types that Sphinx provides:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;:doc:&lt;/span&gt;&lt;/code&gt; for referencing documents&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;:cls:&lt;/span&gt;&lt;/code&gt; for referencing programming classes&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;:term:&lt;/span&gt;&lt;/code&gt; for referencing glossary terms&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;All references support &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;intersphinx&lt;/span&gt;&lt;/code&gt;,
which allows you to prefix your references with a specific project name.
So if your user guide needs to reference your API documentation,
you could do:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;Check out the :cls:`api-ref:api.request`
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;Which would know to look in your &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;api-ref&lt;/span&gt;&lt;/code&gt; project for the class.
The name &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;api-ref&lt;/span&gt;&lt;/code&gt; is arbitrary,
and is defined in your project configuration’s &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;intersphinx_mapping&lt;/span&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;You see the complete set of references in the Sphinx documentation:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;Cross Referencing Syntax - &lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-syntax"&gt;http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-syntax&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Intersphinx - &lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/ext/intersphinx.html"&gt;http://www.sphinx-doc.org/en/stable/ext/intersphinx.html&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/section&gt;
&lt;section id="including-comments-form-source-code"&gt;
&lt;h2&gt;Including comments form source code&lt;/h2&gt;
&lt;p&gt;Integration with code is one of the largest benefits of Sphinx.
You can easily embed software comments from multiple languages,
including Python, Java, and .NET.&lt;/p&gt;
&lt;p&gt;Here is an example of embedding Python documentation for a class in your project:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;Make a request
--------------

You can make requests using the :func:`api.request` module.
It makes HTTP requests against our website.
Here is the basic function signature:

.. autofunction:: api.request
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;As you can see,
you can include generated content in the file that you’re writing by hand.
This allows for building a narrative around generated code comments,
instead of giving your users a separate User Guide and API Reference,
which is often times just an alphabetical listing of code!&lt;/p&gt;
&lt;p&gt;Documentation is best written by humans.
Pulling comments from source code is valuable,
but it should be a small part of a proper set of documentation.&lt;/p&gt;
&lt;p&gt;You can read more about including code comments in the following documentation pages:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;Domains, where the references are defined - &lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/domains.html#what-is-a-domain"&gt;http://www.sphinx-doc.org/en/stable/domains.html#what-is-a-domain&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Autodoc, which generates docs from Python code - &lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/ext/autodoc.html"&gt;http://www.sphinx-doc.org/en/stable/ext/autodoc.html&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Breathe, which bridges doxygen and Sphinx - &lt;a class="reference external" href="https://breathe.readthedocs.io/en/latest/"&gt;https://breathe.readthedocs.io/en/latest/&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;AutoAPI, which bridges .NET and Sphinx - &lt;a class="reference external" href="https://sphinx-autoapi.readthedocs.io/en/latest/"&gt;https://sphinx-autoapi.readthedocs.io/en/latest/&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/section&gt;
&lt;section id="tables"&gt;
&lt;h2&gt;Tables&lt;/h2&gt;
&lt;p&gt;Working with tables can be the bane of anyone who uses plaintext markup languages.
Most other languages require that you write them in the file with some arcane syntax.
However with reStructuredText,
you can use directives to make this much easier.&lt;/p&gt;
&lt;p&gt;You can use either of two powerful list directives,
&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;csv-table&lt;/span&gt;&lt;/code&gt; and &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;list-table&lt;/span&gt;&lt;/code&gt;.
Here is an example of &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;csv-table&lt;/span&gt;&lt;/code&gt;:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Popcorn", 1.99, "Straight from the oven"
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;This shows the inline markup,
however the CSV can also be managed in an external file.
This allows you to manage your complex tables in a third party tool,
and have your documentation consume them from a CSV which is a much nicer workflow.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="internationalization"&gt;
&lt;h2&gt;Internationalization&lt;/h2&gt;
&lt;p&gt;Sphinx includes support for translating documentation into multiple languages.
Since sphinx knows the structure of your documents,
it is able to generate a translatable strings split by each paragraph, heading, or figure.&lt;/p&gt;
&lt;p&gt;Sphinx internationalization works using the &lt;em&gt;gettext&lt;/em&gt; system.
It ships with a builder that allows you to generate a catalog:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="n"&gt;make&lt;/span&gt; &lt;span class="n"&gt;gettext&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;You can then use that catalog as the base translation,
using any tool that supports gettext.
I recommend using Transifex,
which gives you a web-based system for translating the documentation:&lt;/p&gt;
&lt;img alt="https://www.ericholscher.com/_images/transifex.png" src="https://www.ericholscher.com/_images/transifex.png" /&gt;
&lt;p&gt;You can then tell Sphinx what language to generate for its documentation when you build it by setting the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;language&lt;/span&gt;&lt;/code&gt; setting.
Read the Docs also supports internationalization,
allowing you to host multiple languages of your project documentation.&lt;/p&gt;
&lt;p&gt;More information on Sphinx internationalization can be found here:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;&lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/intl.html"&gt;http://www.sphinx-doc.org/en/stable/intl.html&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;a class="reference external" href="http://docs.readthedocs.io/en/latest/localization.html"&gt;http://docs.readthedocs.io/en/latest/localization.html&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/section&gt;
&lt;section id="my-blog"&gt;
&lt;h2&gt;My blog&lt;/h2&gt;
&lt;p&gt;Sphinx is quite versatile,
which means you can use it for a lot of different use cases.
I use a package called &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;ablog&lt;/span&gt;&lt;/code&gt; for hosting of my blog over at &lt;a class="reference external" href="http://ericholscher.com"&gt;http://ericholscher.com&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;The most basic usage allows you to specify that a document is a blog post with the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;post&lt;/span&gt;&lt;/code&gt; directive:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="o"&gt;..&lt;/span&gt; &lt;span class="n"&gt;post&lt;/span&gt;&lt;span class="p"&gt;::&lt;/span&gt; &lt;span class="mi"&gt;2016&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;03&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;15&lt;/span&gt; &lt;span class="mi"&gt;09&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="mi"&gt;00&lt;/span&gt;
   &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;tags&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;writing&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;stc&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;sphinx&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;post&lt;/span&gt;&lt;/code&gt; adds the document to the set of posts.
You can show a post listing by using the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;postlist&lt;/span&gt;&lt;/code&gt; directive:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="o"&gt;..&lt;/span&gt; &lt;span class="n"&gt;postlist&lt;/span&gt;&lt;span class="p"&gt;::&lt;/span&gt;
   &lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;tags&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;stc&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;This shows some of the magical things you can do with Sphinx’s extensibility.
If you’re curious,
this article was actually written in reStructuredText and then exported to Word for publishing.
You can see the full source here: &lt;a class="reference external" href="https://github.com/ericholscher/ericholscher.com/blob/master/site/blog/2016/jul/1/sphinx-and-rtd-for-writers.rst"&gt;https://github.com/ericholscher/ericholscher.com/blob/master/site/blog/2016/jul/1/sphinx-and-rtd-for-writers.rst&lt;/a&gt;&lt;/p&gt;
&lt;/section&gt;
&lt;section id="custom-builders"&gt;
&lt;h2&gt;Custom builders&lt;/h2&gt;
&lt;p&gt;Sphinx supports custom builders to perform tasks beyond providing basic output formats.
Some examples that ship with Sphinx:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;A linkcheck builder that tells you about broken URL’s&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;A builder that outputs all the changes in the latest version of your code for a changelog&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;An XML builder that outputs a representation of your documents in XML&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;A Man page builder that builds man pages from your documentation&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;JSON builder that outputs your pages as HTML inside of JSON, with some metadata, for embedding dynamically&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;You can get as creative as you like with custom builders,
which is another place to extend Sphinx outside of the markup.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="tradeoffs-with-sphinx"&gt;
&lt;h2&gt;Tradeoffs with Sphinx&lt;/h2&gt;
&lt;p&gt;Every tool has its issues and limitations.
I’d like to address some of the issues with Sphinx,
so that you can go into it with eyes wide open.&lt;/p&gt;
&lt;p&gt;The biggest issue is that it is originally a &lt;em&gt;programmer tool&lt;/em&gt;.
This means that a lot of the designs assume knowledge of code,
especially for installation and extending the tools.
Knowledge of the command line is definitely required.&lt;/p&gt;
&lt;p&gt;The markup language,
reStructuredText,
is also a bit finicky.
It depends on whitespace for separation of content,
which is a natural concept for Python programmers,
but not for most writers.&lt;/p&gt;
&lt;p&gt;In general though,
a lot of the complexity in the language comes from the extensibility and power.
When compared to something like Markdown,
reStructuredText can do so much more that it’s worth the complexity and somewhat steep learning curve.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="introduction-to-read-the-docs"&gt;
&lt;h2&gt;Introduction to Read the Docs&lt;/h2&gt;
&lt;p&gt;Read the Docs is a hosting platform for Sphinx-generated documentation.
It takes the power of Sphinx and adds version control,
full-text search,
and other useful features.
It pulls down code and doc files from Git,
Mercurial,
or Subversion,
then builds and hosts your documentation.
We’ll use GitHub in this example as it’s the most commonly used system for accessing code.&lt;/p&gt;
&lt;p&gt;To get started,
you create a Read the Docs account,
and link your GitHub account.
Then you select the GitHub repository you’d like to build documentation for,
at which point the magic happens.&lt;/p&gt;
&lt;p&gt;Read the Docs will:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;Clone your repository&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Build HTML, PDF, and ePub versions of your documentation from your &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;master&lt;/span&gt;&lt;/code&gt; branch.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Index your documentation to allow full-text-search&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Create Version objects from each &lt;em&gt;tag&lt;/em&gt; and &lt;em&gt;branch&lt;/em&gt; in your repository, allowing you to optionally host those as well&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Activate a webhook on your repository, so when you push code to any branch, your documentation is rebuilt&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Now,
whenever you commit new code or documentation to your repository,
your documentation is kept up to date.
This works with your &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;master&lt;/span&gt;&lt;/code&gt; branch,
as well as any other branches or tags you might have activated documentation for.&lt;/p&gt;
&lt;p&gt;Read the Docs has two special versions:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;latest&lt;/span&gt;&lt;/code&gt; which maps to the most up to date development version of your software&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;stable&lt;/span&gt;&lt;/code&gt; which maps to the latest tagged release of your software&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;These are version aliases that help maintain stable URLs for the most up-to-date commits or for the most stable released version of your software.&lt;/p&gt;
&lt;p&gt;We built Read the Docs to be “set it and forget it”.
Once you set your project up and activate the versions you want hosted,
we sit downstream of your version control system and just keep your documentation up to date.
It feels pretty magical once it’s set up,
and takes the thankless task of deploying documentation out of your day.&lt;/p&gt;
&lt;section id="recommended-versioning-system"&gt;
&lt;h3&gt;Recommended Versioning System&lt;/h3&gt;
&lt;p&gt;Read the Docs only works with version control.
This means that however you version your software,
your documentation follows suit.
This is great for integrating with your development team,
but it also means you need to think about the proper strategy for versioning.&lt;/p&gt;
&lt;p&gt;After working with a lot of open source projects,
we generally recommend this workflow for projects:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;A &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;master&lt;/span&gt;&lt;/code&gt; branch that the next release of your software is developed on&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Git &lt;em&gt;branches&lt;/em&gt; for ongoing maintenance of each version of your software that is maintained&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Git &lt;em&gt;tags&lt;/em&gt; for specific released versions that users might be using&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;We recommend release branches because it allows you to update them over time.
Git &lt;em&gt;tags&lt;/em&gt; are static,
so they are appropriate for specific versions that a user might have installed.&lt;/p&gt;
&lt;p&gt;An example:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;master&lt;/span&gt;&lt;/code&gt; is your 2.2 release that isn’t out yet&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;2.1.X&lt;/span&gt;&lt;/code&gt; is your release branch for the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;2.1&lt;/span&gt;&lt;/code&gt; version&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;2.1.1&lt;/span&gt;&lt;/code&gt; is a similar tag of your &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;2.1&lt;/span&gt;&lt;/code&gt; branch, with the latest release&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;2.1.0&lt;/span&gt;&lt;/code&gt; is the first tag of your &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;2.1&lt;/span&gt;&lt;/code&gt; branch&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/section&gt;
&lt;section id="additional-read-the-docs-features"&gt;
&lt;h3&gt;Additional Read the Docs Features&lt;/h3&gt;
&lt;p&gt;Read the Docs also provides the following features:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;GitHub, Bitbucket, and Gitlab webhooks&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Custom domain hosting&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Full-text search for all your projects’ versions&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Status badges to show your docs are up to date&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Hosting of multiple languages for a specific project&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Hosting of multiple projects on a single domain with “subprojects”&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Feel free to email me or find me at a conference if you want to talk more about these concepts,
or have ideas for other neat features.&lt;/p&gt;
&lt;/section&gt;
&lt;/section&gt;
&lt;section id="real-life-examples"&gt;
&lt;h2&gt;Real Life Examples&lt;/h2&gt;
&lt;p&gt;Read the Docs has a large number of users across many different programming languages.
This is in part because Sphinx is such a powerful and dynamic tool,
and Read the Docs makes it easy and free to host docs for your open source project.&lt;/p&gt;
&lt;p&gt;Here are some examples that show the wide range of projects using Sphinx &amp;amp; Read the Docs:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;ASP.NET - Microsoft’s web framework: &lt;a class="reference external" href="https://docs.asp.net"&gt;https://docs.asp.net&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Julia - A language for scientific computing: &lt;a class="reference external" href="http://docs.julialang.org"&gt;http://docs.julialang.org&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Jupyter - An interactive programming environment: &lt;a class="reference external" href="http://jupyter.readthedocs.io"&gt;http://jupyter.readthedocs.io&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;PHPMyAdmin - A web-based database editor: &lt;a class="reference external" href="https://docs.phpmyadmin.net"&gt;https://docs.phpmyadmin.net&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Write the Docs - The community site for Write the Docs - &lt;a class="reference external" href="http://www.writethedocs.org"&gt;http://www.writethedocs.org&lt;/a&gt;&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;As you can see,
a wide range of projects are using the tools for many different uses.
It’s a powerful tool for writing prose as well as documenting source code.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="going-forward"&gt;
&lt;h2&gt;Going Forward&lt;/h2&gt;
&lt;p&gt;Sphinx is an incredibly powerful tool.
Read the Docs builds on top to provide hosting for Sphinx documentation that keeps your docs up to date across versions.
Together,
they are a wonderful set of tools that developers and technical writers both enjoy using.&lt;/p&gt;
&lt;p&gt;I firmly believe that the more integrated with the product development process technical writers get,
the better our products get.
Tools that integrate documentation and development workflows make it much easier for writers to become part of the larger development process.
Sphinx and Read the Docs have been battle tested by hundreds of thousands of open source developers for years,
and are a great choice for your software documentation project.&lt;/p&gt;
&lt;div class="admonition note"&gt;
&lt;p class="admonition-title"&gt;Note&lt;/p&gt;
&lt;p&gt;Eric Holscher offers &lt;a class="reference external" href="https://readthedocs.com/services/"&gt;consulting and contracting&lt;/a&gt; on work related to Sphinx. If you want help implementing it in your organization, feel free to reach out and hopefully we can work together.&lt;/p&gt;
&lt;/div&gt;
&lt;/section&gt;
&lt;/section&gt;
</content>
    <link href="https://www.ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/"/>
    <summary>Treating documentation as code is becoming a major theme in the software industry.
This is coming from both sides,
with developers starting to treat documentation as a priority alongside tests and code,
and writers seeing a lot of value in integrating more into the development process.
This marrying of cultures isn’t simple,
but having the proper tools for the job makes both sides happy with the process and the results that get produced.</summary>
    <category term="article" label="article"/>
    <category term="rst" label="rst"/>
    <category term="sphinx" label="sphinx"/>
    <category term="technicalwriters" label="technical writers"/>
    <published>2016-07-01T00:00:00+00:00</published>
  </entry>
  <entry>
    <id>https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/</id>
    <title>Why You Shouldn’t Use “Markdown” for Documentation</title>
    <updated>2016-03-15T09:00:00+00:00</updated>
    <content type="html">&lt;section id="why-you-shouldn-t-use-markdown-for-documentation"&gt;

&lt;div class="admonition note"&gt;
&lt;p class="admonition-title"&gt;Note&lt;/p&gt;
&lt;p&gt;This post was written in 2016, and the landscape here has changed. I still mostly agree with what is important, but the “Markdown” ecosystem has evolved and gotten other capabilities that might change the calculus of what is the right tool for your organization.&lt;/p&gt;
&lt;/div&gt;
&lt;p&gt;&lt;a class="reference external" href="https://github.com/jgm/CommonMark/wiki/Markdown-Flavors"&gt;“Markdown”&lt;/a&gt; is the most commonly used lightweight markup language on the internet.
It is great for a subset of tasks,
mainly blog posts and commenting.
However,
lately it has been adopted by the technical writing community as a solution for writing documentation.&lt;/p&gt;
&lt;p&gt;I’d like to lay out the main arguments that I have against Markdown.
Hopefully this will be useful in helping you decide whether it’s a good fit for your organization.
If you are considering Markdown,
I hope that you also look at &lt;a class="reference external" href="http://asciidoctor.org/"&gt;Asciidoctor&lt;/a&gt; and &lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/"&gt;Sphinx&lt;/a&gt;.
I find them to be much better toolsets for writing documentation.&lt;/p&gt;
&lt;p&gt;Markdown is often chosen because it’s viewed as a simple approach that handles the basic cases well.
Developers prefer it because GitHub supports it,
though GitHub supports &lt;a class="reference external" href="https://github.com/github/markup#markups"&gt;9 different markup languages&lt;/a&gt;,
including &lt;a class="reference external" href="http://asciidoctor.org/docs/asciidoc-writers-guide/"&gt;Asciidoc&lt;/a&gt; and &lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/rest.html"&gt;reStructuredText&lt;/a&gt;.
As documentation grows from a few pages into a large set of documents,
Markdown quickly falls over and becomes a liability instead of a benefit.
I’d like to explain a bit more about why this is the case.&lt;/p&gt;
&lt;section id="lack-of-a-standard"&gt;
&lt;h2&gt;Lack of a standard&lt;/h2&gt;
&lt;p&gt;For a long time,
Markdown was defined by the &lt;a class="reference external" href="https://daringfireball.net/projects/markdown/"&gt;initial implementation&lt;/a&gt; written by John Gruber.
There was no spec,
and the “proper” behavior was whatever this script chose to do.&lt;/p&gt;
&lt;p&gt;As Markdown got popular,
more and more sites started to implement it.
Those sites were written in other languages,
so more implementations of Markdown were created.
All of these implementations had slight variations in what was accepted.&lt;/p&gt;
&lt;p&gt;One example is that some required a space before a heading and others didn’t:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="c1"&gt;# Heading 1&lt;/span&gt;

&lt;span class="c1"&gt;#Heading 1&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;There are a number of small issues that made it hard to port your Markdown between sites and versions.&lt;/p&gt;
&lt;p&gt;In the last few years, &lt;a class="reference external" href="http://commonmark.org/"&gt;Commonmark&lt;/a&gt; was developed as a standardized Markdown.
This is great,
and should solve lots of problems!
Except that nobody has adopted it…&lt;/p&gt;
&lt;/section&gt;
&lt;section id="flavors"&gt;
&lt;h2&gt;Flavors&lt;/h2&gt;
&lt;p&gt;The main reason for this lack of adoption is that people using Markdown haven’t been sitting still for all these years.
Because the original Markdown is so limited,
every popular tool built on top of Markdown implements what is called a “&lt;a class="reference external" href="https://github.com/jgm/CommonMark/wiki/Markdown-Flavors"&gt;flavor&lt;/a&gt;” of Markdown.
This sounds great,
except that &lt;strong&gt;every tool implements a different flavor&lt;/strong&gt;.
Even tools that do similar things with the language use different syntax for it!&lt;/p&gt;
&lt;p&gt;For example,
in &lt;a class="reference external" href="https://michelf.ca/projects/php-markdown/extra/#fenced-code-blocks"&gt;Markdown Extra&lt;/a&gt; code blocks look like this:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="o"&gt;~~~&lt;/span&gt; &lt;span class="o"&gt;.&lt;/span&gt;&lt;span class="n"&gt;python&lt;/span&gt;

&lt;span class="kn"&gt;import&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nn"&gt;antigravity&lt;/span&gt;

&lt;span class="o"&gt;~~~&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;This would apply a &lt;cite&gt;python&lt;/cite&gt; class to the HTML block that is output.&lt;/p&gt;
&lt;p&gt;However,
with &lt;a class="reference external" href="https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown"&gt;GitHub Flavored Markdown&lt;/a&gt; the same example would be:&lt;/p&gt;
&lt;div class="highlight-default notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;```python

import antigravity

```
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;This would apply syntax highlighting to the actual rendered HTML output.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;This is two different syntaxes for a similar concept, both called “Markdown”&lt;/strong&gt;&lt;/p&gt;
&lt;/section&gt;
&lt;section id="lack-of-extensibility"&gt;
&lt;h2&gt;Lack of Extensibility&lt;/h2&gt;
&lt;p&gt;With other markup languages,
you can extend the language to provide the features that you need.
They have mechanisms in the syntax to add new functionality,
without breaking from the original spec and creating a new language.&lt;/p&gt;
&lt;p&gt;reStructuredText for example,
has both inline and block level markup:&lt;/p&gt;
&lt;div class="highlight-rst notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="p"&gt;..&lt;/span&gt; &lt;span class="ow"&gt;contents&lt;/span&gt;&lt;span class="p"&gt;::&lt;/span&gt; All the stuff I'm going to talk about
   &lt;span class="nc"&gt;:depth:&lt;/span&gt; 2

Please look at &lt;span class="na"&gt;:rfc:&lt;/span&gt;&lt;span class="nv"&gt;`1984`&lt;/span&gt; for more information.
This is implemented in our codebase at &lt;span class="na"&gt;:class:&lt;/span&gt;&lt;span class="nv"&gt;`Example.Encryption`&lt;/span&gt;.
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;You can learn more about the &lt;a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/roles.html#rfc-reference"&gt;rfc&lt;/a&gt;, &lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/domains.html?highlight=domains#cross-referencing-python-objects"&gt;class&lt;/a&gt;, and &lt;a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents"&gt;contents&lt;/a&gt; concepts.&lt;/p&gt;
&lt;p&gt;As a developer working with rST or Asciidoctor,
I can add new markup to the language in a simple,
pluggable way.
I don’t have to change how the language is parsed,
and I can share those additions with other users via a standard extension mechanism.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;There is no way of doing this in Markdown,
in a way that would be portable across versions.&lt;/strong&gt;&lt;/p&gt;
&lt;div class="admonition note"&gt;
&lt;p class="admonition-title"&gt;Note&lt;/p&gt;
&lt;p&gt;CommonMark is working on an &lt;a class="reference external" href="http://talk.commonmark.org/t/generic-directives-plugins-syntax/444"&gt;extensibility syntax&lt;/a&gt;, but it isn’t implemented yet.&lt;/p&gt;
&lt;/div&gt;
&lt;/section&gt;
&lt;section id="lack-of-semantic-meaning"&gt;
&lt;h2&gt;Lack of Semantic Meaning&lt;/h2&gt;
&lt;p&gt;Though many people have added extensions to Markdown,
almost none have any kind of semantic meaning.
This means that you can’t write a &lt;em&gt;Class&lt;/em&gt; or a &lt;em&gt;Warning&lt;/em&gt;,
you can only write text.&lt;/p&gt;
&lt;p&gt;This leads people to embed HTML directly in their Markdown:&lt;/p&gt;
&lt;div class="highlight-html notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nt"&gt;div&lt;/span&gt; &lt;span class="na"&gt;class&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"warning"&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;

This is a Warning!

&lt;span class="p"&gt;&amp;lt;/&lt;/span&gt;&lt;span class="nt"&gt;div&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;In reStructuredText for example,
you can write:&lt;/p&gt;
&lt;div class="highlight-rst notranslate"&gt;&lt;div class="highlight"&gt;&lt;pre&gt;&lt;span&gt;&lt;/span&gt;&lt;span class="p"&gt;..&lt;/span&gt; &lt;span class="ow"&gt;warning&lt;/span&gt;&lt;span class="p"&gt;::&lt;/span&gt; This is a Warning!
&lt;/pre&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;p&gt;This will be output as a warning properly in HTML, PDF, and any other output format you can generate.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Semantic markup firmly separates the words that you write from how they are displayed.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Writing without semantic markup is a problem for a few reasons:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;Your Markdown is now dependent on specific CSS classes in your display, meaning your writers have to think about how your page will be designed&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Your content is no longer portable to other output formats (PDF, etc.)&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Conversion to other markup tools and page designs becomes much harder&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;div class="admonition note"&gt;
&lt;p class="admonition-title"&gt;Note&lt;/p&gt;
&lt;p&gt;I have covered the ideas around semantics more in my post &lt;a class="reference internal" href="../../../2016/oct/6/authoring-documentation-with-semantic-meaning/#semantic-meaning"&gt;&lt;span class="std std-ref"&gt;Semantic Meaning in Authoring Documentation&lt;/span&gt;&lt;/a&gt;.&lt;/p&gt;
&lt;/div&gt;
&lt;/section&gt;
&lt;section id="lock-in-and-lack-of-portability"&gt;
&lt;h2&gt;Lock In and Lack of Portability&lt;/h2&gt;
&lt;p&gt;The explosion of flavors and lack of semantic meaning leads to lock in.
Once you’ve built out a large set of Markdown documents,
it’s quite hard to migrate them to another tool,
even if that tool claims to support Markdown!
You have a large set of custom HTML classes and weird flavor extensions that won’t work anywhere but the current set of tools and designs.&lt;/p&gt;
&lt;p&gt;You also can’t migrate Markdown easily to another markup language (Asciidoc or RST),
because Pandoc and other conversion tools won’t support your flavor’s extensions.&lt;/p&gt;
&lt;p&gt;I think that a lot of people choose Markdown because they think they can migrate to another tool or markup later.
Markdown is definitely the lowest common denominator,
except that for any reasonably sized set of docs you’ll need things that aren’t in the basic language.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Once you start using markdown flavors,
which is required for any non-trivial documentation,
you lose all portability benefits.&lt;/strong&gt;&lt;/p&gt;
&lt;/section&gt;
&lt;section id="conclusion"&gt;
&lt;h2&gt;Conclusion&lt;/h2&gt;
&lt;p&gt;I believe that CommonMark is a good step forward,
and if it became more widely used,
and added extension support,
I could whole-heartedly recommend it as a solution to this problem.
The current ecosystem we have around Markdown is not something that I can endorse,
and believe that it’s actively holding back folks to want to make documentation better.&lt;/p&gt;
&lt;p&gt;I hope that we can start to move forward with a more standardized set of languages,
including CommonMark, reStructuredText, and Asciidoc,
fully supporting them across the suite of tools that we use.
For now, please investigate &lt;a class="reference external" href="http://www.sphinx-doc.org/en/stable/"&gt;Sphinx&lt;/a&gt; and &lt;a class="reference external" href="http://asciidoctor.org/"&gt;Asciidoctor&lt;/a&gt; as good alternatives.
They come with a lot more extensibility built into the language,
and are more complete tools for building sets of documentation today.&lt;/p&gt;
&lt;p&gt;Markdown is a concept more than it is an implementation.
It generally means “a set of incompatible extensions to something that looks kinda like Markdown”.
When you are trying to author large sets of documents,
it isn’t the correct tool.&lt;/p&gt;
&lt;p&gt;&lt;em&gt;Full Disclosure:&lt;/em&gt; I work on a product, &lt;a class="reference external" href="https://readthedocs.com/"&gt;Read the Docs&lt;/a&gt;, which is based on Sphinx, so my views are likely biased.&lt;/p&gt;
&lt;/section&gt;
&lt;/section&gt;
</content>
    <link href="https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/"/>
    <summary>This post was written in 2016, and the landscape here has changed. I still mostly agree with what is important, but the “Markdown” ecosystem has evolved and gotten other capabilities that might change the calculus of what is the right tool for your organization.</summary>
    <published>2016-03-15T09:00:00+00:00</published>
  </entry>
  <entry>
    <id>https://www.ericholscher.com/blog/2015/may/25/why-im-building-a-company-structure/</id>
    <title>Why I’m building a company: Structure</title>
    <updated>2015-05-25T12:00:00+00:00</updated>
    <content type="html">&lt;section id="why-i-m-building-a-company-structure"&gt;

&lt;p&gt;There are a lot of reasons to build a new &lt;a class="reference external" href="https://readthedocs.com"&gt;company&lt;/a&gt;.
A large part of it is wanting something to exist in the world.
However,
there are ways to manifest things that don’t require a new company.&lt;/p&gt;
&lt;p&gt;The idea of a company itself being important came to me mostly from Steve Jobs.
The canonical biography talks a lot about him building the company specifically,
with the below understanding:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Company: A structure to build sustainable culture and values that live beyond yourself.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;This was something I’d understood in a partial way,
but the book made the concept concrete.&lt;/p&gt;
&lt;section id="structure"&gt;
&lt;h2&gt;Structure&lt;/h2&gt;
&lt;p&gt;I believe there is a lot wrong with the ways companies are currently structured.
The biggest issue is the concept of a 40-hour work week.
All creative people I know strife at the concept of working 40 hours a week.&lt;/p&gt;
&lt;p&gt;Most folks admit they don’t have 40 hours of creative potential within a week.
Usually they get about 4-5 hours a day,
at most,
of truly creative and productive time.
Within a classic, &lt;em&gt;officed&lt;/em&gt;, 9-5ish company,
the rest is meetings, filler, and “fun”.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="exostructure"&gt;
&lt;h2&gt;Exostructure&lt;/h2&gt;
&lt;p&gt;As much as you want to change a company,
you can’t change the culture around the company,
at least to start.
The biggest element that can’t be changed immediately:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;Monday-Friday 9-5ish availability&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Weekends as time off&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Luckily creativity loves constraints,
and these are the constraints that I am working with.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="idea"&gt;
&lt;h2&gt;Idea&lt;/h2&gt;
&lt;p&gt;Two separate working teams:&lt;/p&gt;
&lt;ul class="simple"&gt;
&lt;li&gt;&lt;p&gt;Monday-Wednesday Team&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Wednesday-Friday Team&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Working ~20 hours a week&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The idea is that there are two separate teams working on either the same or similar projects.
Wednesday would be the shared day where people would transfer knowledge and hand off projects which require handoff.
It would also be for brainstorming,
so people fresh from not working and folks deep in the project could work together.&lt;/p&gt;
&lt;p&gt;I imagine this would work better on some teams than others,
but I generally believe it would allow people to live better lives,
and do better work.&lt;/p&gt;
&lt;p&gt;It would also require a lot more documentation :)&lt;/p&gt;
&lt;/section&gt;
&lt;section id="why"&gt;
&lt;h2&gt;Why?&lt;/h2&gt;
&lt;p&gt;I live for the woods.
You may live for something else,
but it is most certainly not &lt;em&gt;work&lt;/em&gt;.
I enjoy my work in a profound way,
but work is only a subset of life.
By promoting life outside of work,
and giving people more time to live,
we will all be happier.&lt;/p&gt;
&lt;p&gt;Happier people build better products and companies.&lt;/p&gt;
&lt;p&gt;Working less also requires more discipline.
You have to &lt;a class="reference external" href="https://al3x.net/2010/01/09/dont-be-a-hero.html"&gt;kill your heroes&lt;/a&gt;,
and work in the time meant for work to be done.
A structure that reinforces balance provides the right incentive structure.
&lt;strong&gt;If I can’t work all the time,
the work has to be good,
supportable,
and documented.&lt;/strong&gt;&lt;/p&gt;
&lt;/section&gt;
&lt;section id="crazy"&gt;
&lt;h2&gt;Crazy?&lt;/h2&gt;
&lt;p&gt;We haven’t implemented this concept yet.
I’d be curious of previous examples of this kind of structure working,
or failing.
I imagine there are subsets of a company where this might make perfect sense (customer support, operations),
because there is a shared context.
There are also likely situations where it wouldn’t work,
but I’m really excited to try things like this.&lt;/p&gt;
&lt;p&gt;Why build a company if it’s going to be like every other company?&lt;/p&gt;
&lt;/section&gt;
&lt;/section&gt;
</content>
    <link href="https://www.ericholscher.com/blog/2015/may/25/why-im-building-a-company-structure/"/>
    <summary>There are a lot of reasons to build a new company.
A large part of it is wanting something to exist in the world.
However,
there are ways to manifest things that don’t require a new company.</summary>
    <published>2015-05-25T12:00:00+00:00</published>
  </entry>
  <entry>
    <id>https://www.ericholscher.com/blog/2014/oct/24/announcing-read-the-docs-for-business/</id>
    <title>Announcing Read the Docs for Business</title>
    <updated>2014-10-24T10:00:00+00:00</updated>
    <content type="html">&lt;section id="announcing-read-the-docs-for-business"&gt;

&lt;p&gt;I helped &lt;a class="reference external" href="http://ericholscher.com/blog/2010/aug/16/announcing-read-docs/"&gt;create&lt;/a&gt; Read the Docs over four years ago.
It started with a humble goal of replacing a cron job on my own server.
Since then,
it &lt;a class="reference external" href="http://ericholscher.com/blog/2013/dec/23/read-the-docs-2013-stats/"&gt;has grown&lt;/a&gt; more than I ever could have &lt;a class="reference external" href="http://www.seethestats.com/site/readthedocs.org"&gt;imagined&lt;/a&gt;.
It has become vital infrastructure for the Python community,
and the &lt;a class="reference external" href="http://ericholscher.com/blog/2014/feb/11/sphinx-isnt-just-for-python/"&gt;programming world&lt;/a&gt; in general.&lt;/p&gt;
&lt;p&gt;Read the Docs has always been a volunteer effort for me.
I have gotten small amounts from &lt;a class="reference external" href="http://ericholscher.com/blog/2013/sep/25/help-me-improve-documentation/"&gt;Gittip&lt;/a&gt; over the years,
but it doesn’t compare to a developer’s salary
It has been a labor of love because I &lt;a class="reference external" href="http://ericholscher.com/blog/2012/jan/22/why-read-docs-matters/"&gt;really believe&lt;/a&gt; in improving documentation for developers &lt;a class="footnote-reference brackets" href="#f1" id="id1" role="doc-noteref"&gt;&lt;span class="fn-bracket"&gt;[&lt;/span&gt;1&lt;span class="fn-bracket"&gt;]&lt;/span&gt;&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;Companies have the same issues with documentation that open source has. &lt;a class="footnote-reference brackets" href="#f2" id="id2" role="doc-noteref"&gt;&lt;span class="fn-bracket"&gt;[&lt;/span&gt;2&lt;span class="fn-bracket"&gt;]&lt;/span&gt;&lt;/a&gt;
Since Read the Docs is open source,
it’s been possible to run it locally at your company.
However,
running Read the Docs is not trivial.
There are a lot of moving pieces,
and the code base is always gaining new features.&lt;/p&gt;
&lt;p&gt;That’s why today,
Read the Docs is adding a hosted solution aimed at companies.
It will host your company’s private documentation,
and only give people at your company access.&lt;/p&gt;
&lt;section id="readthedocs-com"&gt;
&lt;h2&gt;readthedocs.com&lt;/h2&gt;
&lt;p&gt;This site will live at &lt;a class="reference external" href="https://readthedocs.com"&gt;https://readthedocs.com&lt;/a&gt;.
The profits from the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;.com&lt;/span&gt;&lt;/code&gt; will help fund development on the &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;.org&lt;/span&gt;&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;We’ve also added some features that only make sense for companies.
Since everyone is logged in,
you can see who is reading each page.
This lets you focus your writing on pages that get read.&lt;/p&gt;
&lt;p&gt;&lt;a class="reference external" href="https://readthedocs.com"&gt;https://readthedocs.com&lt;/a&gt; is launching today with a private beta.
You can sign up for invites now,
and we will start letting people in soon.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="why-a-com-and-a-org"&gt;
&lt;h2&gt;Why a .com and a .org&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;readthedocs.org will always be free and available for open source docs.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;I love &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;readthedocs.org&lt;/span&gt;&lt;/code&gt;,
and I never want anything to happen to it.
&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;readthedocs.com&lt;/span&gt;&lt;/code&gt; is a separate entity that has been established to bring Read the Docs to business.&lt;/p&gt;
&lt;p&gt;This has been a lot of work.
Having both live on the same domain would be much easier,
but I strongly believe &lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;readthedocs.org&lt;/span&gt;&lt;/code&gt; should never be part of “&lt;a class="reference external" href="http://ourincrediblejourney.tumblr.com/"&gt;an incredible journey&lt;/a&gt;”.
As part of that, we are bootstrapping, and do not plan on taking venture funding. &lt;a class="footnote-reference brackets" href="#f3" id="id3" role="doc-noteref"&gt;&lt;span class="fn-bracket"&gt;[&lt;/span&gt;3&lt;span class="fn-bracket"&gt;]&lt;/span&gt;&lt;/a&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The fate of readthedocs.org is not tied to the fate of the business.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;readthedocs.com&lt;/span&gt;&lt;/code&gt; has been created to help fund work on the open source project.
&lt;code class="docutils literal notranslate"&gt;&lt;span class="pre"&gt;readthedocs.org&lt;/span&gt;&lt;/code&gt; should be a resource available to the programming community forever,
and I am doing everything in my power to make sure that happens.&lt;/p&gt;
&lt;p&gt;Creating a company will help make both the open source and corporate documentation worlds better.
Read the Docs solves a real need in the software world,
and I hope you join us in the next stage.&lt;/p&gt;
&lt;p&gt;Our mission is to build world-class documentation tools for developers,
and we would love to have you aboard.&lt;/p&gt;
&lt;br&gt;
&lt;br&gt;&lt;aside class="footnote-list brackets"&gt;
&lt;aside class="footnote brackets" id="f1" role="doc-footnote"&gt;
&lt;span class="label"&gt;&lt;span class="fn-bracket"&gt;[&lt;/span&gt;&lt;a role="doc-backlink" href="#id1"&gt;1&lt;/a&gt;&lt;span class="fn-bracket"&gt;]&lt;/span&gt;&lt;/span&gt;
&lt;p&gt;During this time,
I’ve also co-founded &lt;a class="reference external" href="http://conf.writethedocs.org/"&gt;documentation conferences&lt;/a&gt; in the US and Europe.
We’re building community around people who care about this issue.
The conference is also run as a non-profit endeavor,
in our effort to build community.&lt;/p&gt;
&lt;/aside&gt;
&lt;aside class="footnote brackets" id="f2" role="doc-footnote"&gt;
&lt;span class="label"&gt;&lt;span class="fn-bracket"&gt;[&lt;/span&gt;&lt;a role="doc-backlink" href="#id2"&gt;2&lt;/a&gt;&lt;span class="fn-bracket"&gt;]&lt;/span&gt;&lt;/span&gt;
&lt;p&gt;Actually, most companies have it way worse. Hell, most of them still store their docs in a &lt;strong&gt;wiki&lt;/strong&gt;.&lt;/p&gt;
&lt;/aside&gt;
&lt;aside class="footnote brackets" id="f3" role="doc-footnote"&gt;
&lt;span class="label"&gt;&lt;span class="fn-bracket"&gt;[&lt;/span&gt;&lt;a role="doc-backlink" href="#id3"&gt;3&lt;/a&gt;&lt;span class="fn-bracket"&gt;]&lt;/span&gt;&lt;/span&gt;
&lt;p&gt;We have taken $20,000 as part of being in &lt;a class="reference external" href="http://www.piepdx.com/"&gt;PIE&lt;/a&gt; with the explicit understanding that we are not seeking further venture funding. They are amazing folks and I thank them sincerely. The business likely never would have happened without the office space and mentoring they provided.&lt;/p&gt;
&lt;/aside&gt;
&lt;/aside&gt;
&lt;/section&gt;
&lt;/section&gt;
</content>
    <link href="https://www.ericholscher.com/blog/2014/oct/24/announcing-read-the-docs-for-business/"/>
    <summary>I helped create Read the Docs over four years ago.
It started with a humble goal of replacing a cron job on my own server.
Since then,
it has grown more than I ever could have imagined.
It has become vital infrastructure for the Python community,
and the programming world in general.</summary>
    <published>2014-10-24T10:00:00+00:00</published>
  </entry>
  <entry>
    <id>https://www.ericholscher.com/blog/2014/aug/8/read-the-docs-goes-full-time/</id>
    <title>Read the Docs goes full-time</title>
    <updated>2014-08-08T00:00:00+00:00</updated>
    <content type="html">&lt;section id="read-the-docs-goes-full-time"&gt;

&lt;p&gt;We have some exciting news in Read the Docs land this week.
The project has been &lt;a class="reference external" href="http://blog.piepdx.com/2014/08/05/announcing-pie-class-of-2014/"&gt;accepted into&lt;/a&gt; the Portland Incubator Experiment,
as an open source project.
This means that we have office space provided to us in Portland for three months,
where we will be working on Read the Docs full-time.
There will be two of us working on this:
&lt;a class="reference external" href="http://twitter.com/ericholscher"&gt;Eric Holscher&lt;/a&gt; and &lt;a class="reference external" href="https://twitter.com/agjhnsn"&gt;Anthony Johnson&lt;/a&gt;.&lt;/p&gt;
&lt;div class="admonition note"&gt;
&lt;p class="admonition-title"&gt;Note&lt;/p&gt;
&lt;p&gt;Because we now have amazing office space,
you can drop by and hack with us any time.
We will be in &lt;a class="reference external" href="https://www.google.com/maps/place/Portland+Incubator+Experiment/&amp;#64;45.52441,-122.683594,17z/data=!3m1!4b1!4m2!3m1!1s0x54950a02699da207:0xc065b43c82957842"&gt;Downtown Portland&lt;/a&gt; every weekday.
Come work on Read the Docs with us!&lt;/p&gt;
&lt;/div&gt;
&lt;p&gt;This is a fantastic opportunity for the project.
Having two engineers working on it for three months will enable us to build a lot of useful things.
This week is the first week,
and we have already &lt;a class="reference external" href="https://github.com/rtfd/readthedocs.org/pulse"&gt;triaged the entire issue tracker&lt;/a&gt; and launched a few new features.&lt;/p&gt;
&lt;section id="new-features"&gt;
&lt;h2&gt;New Features&lt;/h2&gt;
&lt;p&gt;Historically,
we haven’t had a great way to announce new features.
We would tweet them from the &lt;a class="reference external" href="http://twitter.com/readthedocs"&gt;&amp;#64;readthedocs&lt;/a&gt; account,
and hope people followed us.
This isn’t a great format for showing new things.&lt;/p&gt;
&lt;p&gt;Today we are announcing a new blog: &lt;a class="reference external" href="http://blog.readthedocs.com/"&gt;http://blog.readthedocs.com/&lt;/a&gt;
We will be doing regular feature announcements on the blog as we build them.
There are a number of recently released features that we’ll be highlighting there.
If reading on the web isn’t your thing,
you can also choose to get that content via &lt;a class="reference external" href="http://blog.readthedocs.com/archive/atom.xml"&gt;RSS&lt;/a&gt; or email:&lt;/p&gt;
&lt;!-- Begin MailChimp Signup Form --&gt;
&lt;div id="mc_embed_signup"&gt;
&lt;form action="//readthedocs.us3.list-manage.com/subscribe/post?u=a6a22369cc2b356379cf789ca&amp;amp;id=a85a83a5a5" method="post" id="mc-embedded-subscribe-form" name="mc-embedded-subscribe-form" class="validate" target="_blank" novalidate&gt;
    &lt;input type="email" value="" name="EMAIL" class="email" id="mce-EMAIL" placeholder="email address" required&gt;
    &lt;!-- real people should not fill this in and expect good things - do not remove this or risk form bot signups--&gt;
    &lt;div style="position: absolute; left: -5000px;"&gt;&lt;input type="text" name="b_a6a22369cc2b356379cf789ca_a85a83a5a5" tabindex="-1" value=""&gt;&lt;/div&gt;
    &lt;input type="submit" value="Subscribe" name="subscribe" id="mc-embedded-subscribe" class="button"&gt;
&lt;/form&gt;
&lt;/div&gt;

&lt;!--End mc_embed_signup--&gt;&lt;p&gt;Adding new features to the project is great in the short term,
but something like Read the Docs needs support for the long term.
To be able to continue doing Read the Docs,
we have decided to spend this time figuring out how to make the project sustainable.&lt;/p&gt;
&lt;/section&gt;
&lt;section id="sustainability"&gt;
&lt;h2&gt;Sustainability&lt;/h2&gt;
&lt;p&gt;We hope at the end of three months that Read the Docs is a sustainable open source project.
We will have more information on this front in the next few weeks,
as we figure out what our sustainability model will look like.
The goal is that we will be able to create new features and support hosting the project for years to come.
If you have thoughts on good ways to do this,
feel free to &lt;a class="reference external" href="mailto:eric&amp;#37;&amp;#52;&amp;#48;ericholscher&amp;#46;com"&gt;email me&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;We really believe in the mission and potential of Read the Docs to improve the state of documentation in software,
and we are happy with how far we’ve come.
However,
this is just the beginning,
and we look forward to building the future with you.&lt;/p&gt;
&lt;/section&gt;
&lt;/section&gt;
</content>
    <link href="https://www.ericholscher.com/blog/2014/aug/8/read-the-docs-goes-full-time/"/>
    <summary>We have some exciting news in Read the Docs land this week.
The project has been accepted into the Portland Incubator Experiment,
as an open source project.
This means that we have office space provided to us in Portland for three months,
where we will be working on Read the Docs full-time.
There will be two of us working on this:
Eric Holscher and Anthony Johnson.</summary>
    <published>2014-08-08T00:00:00+00:00</published>
  </entry>
</feed>
