http://ericholscher.comEric Holscher - Posts tagged semantic meaning2024-02-28T16:22:29.066190+00:00ABloghttp://ericholscher.com/blog/2016/oct/6/authoring-documentation-with-semantic-meaning/Semantic Meaning in Authoring Documentation2016-10-06T00:00:00+00:00<section id="semantic-meaning-in-authoring-documentation">
<span id="semantic-meaning"></span>
<p>Semantic Meaning in documentation is the separation of what something is from what it looks like.
What we <em>mean</em> and what we <em>display</em> are very different things.</p>
<p>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.</p>
<section id="semantics">
<h2>Semantics</h2>
<p>As an example,
if we were writing documentation in HTML,
we could warn a user with bold:</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">b</span><span class="p">></span>
Don't do this, it will break your system!
<span class="p"></</span><span class="nt">b</span><span class="p">></span>
</pre></div>
</div>
<p>This has no semantics.
<em>Bold doesn’t mean “warning”,
it is simply a way of displaying text.</em>
A better example in HTML is:</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">span</span> <span class="na">class</span><span class="o">=</span><span class="s">"warning"</span><span class="p">></span>
Don't do this, it will break your system!
<span class="p"></</span><span class="nt">span</span><span class="p">></span>
</pre></div>
</div>
<p>This allows you to write <em>what</em> something is,
but not have to worry about what it looks like.
Your designer might decide that warnings should be bold and red:</p>
<div class="highlight-css notranslate"><div class="highlight"><pre><span></span><span class="p">.</span><span class="nc">warning</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">text-format</span><span class="p">:</span><span class="w"> </span><span class="kc">bold</span><span class="p">;</span>
<span class="w"> </span><span class="k">color</span><span class="p">:</span><span class="w"> </span><span class="kc">red</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The important part is that you don’t need to think about what warnings look like,
just that it’s a warning.</p>
<p>To go one step further,
in <a class="reference external" href="http://www.sphinx-doc.org/en/stable/rest.html">reStructuredText</a> we can do:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">warning</span><span class="p">::</span> Don't do this, it will break your system!
</pre></div>
</div>
<p>Then <a class="reference external" href="http://www.sphinx-doc.org">Sphinx</a> 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.</p>
<p>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.</p>
</section>
<section id="value-of-semantic-documentation">
<h2>Value of Semantic Documentation</h2>
<p>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 <em>think</em> in terms of <em>warnings</em>,
<em>references</em>,
<em>classes</em>,
<em>objects</em>,
and other powerful semantic constructs.</p>
<p>You start thinking in terms of <em>nouns</em> that can be represented in your problem domain.
You can then encode this model into your document:</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">warning</span><span class="p">::</span> Make sure you <span class="na">:term:</span><span class="nv">`instantiate`</span>
the Response objects before you use it.
You can read more about the <span class="na">:cls:</span><span class="nv">`django.http.Response`</span>
in our <span class="na">:doc:</span><span class="nv">`/api/response`</span> page.
</pre></div>
</div>
<p>In the above section,
I thought <em>Hey, maybe someone doesn’t know what instantiate means.</em>
I was able to link to the glossary with <code class="docutils literal notranslate"><span class="pre">:term:</span></code>.
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.
<strong>I was able to simply write what I meant,
and move on.</strong></p>
<p>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.</p>
<p>Semantic information also acts as a type of documentation for our writing.
Similar to <a class="reference external" href="https://en.wikipedia.org/wiki/Type_system">type systems</a> in programming,
they allow you to be explicit about what you’re talking about.
When you write documentation about a <code class="docutils literal notranslate"><span class="pre">Response</span></code> object,
it isn’t immediately obvious <em>what</em> that is.
When you write about a <code class="docutils literal notranslate"><span class="pre">:cls:`django.http.Response`</span></code>,
it is explicitly defined what you’re talking about.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>When you write documentation in Markdown,
there is no clear way to represent semantic information.
You can make something <em>bold</em>,
but you can’t make something a <em>warning</em>.</p>
<p>Please <a class="reference internal" href="../../../2016/mar/15/dont-use-markdown-for-technical-docs/"><span class="doc">don’t write documentation in Markdown</span></a>.</p>
</div>
</section>
<section id="conclusion">
<h2>Conclusion</h2>
<p>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.</p>
<p>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.</p>
<p>You should write in a format that gives you the most semantic meaning possible.
This:</p>
<ul class="simple">
<li><p>Allows you to focus on communicating information, not thinking about what HTML class you need for a concept</p></li>
<li><p>Expand your own ability to think about your writing in terms of semantic nouns, allowing you to better structure your thoughts</p></li>
<li><p>Allows tooling to raise errors when you try to reference semantic concepts that doesn’t exist (typos, etc.)</p></li>
<li><p>Give people updating your documents explicit information about what you’re documenting</p></li>
<li><p>Allows your documentation systems to crosslink information and provide a better experience for your user</p></li>
<li><p>Allows your designer to apply consistent styles to all types of information</p></li>
</ul>
<p>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.</p>
</section>
</section>
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.2016-10-06T00:00:00+00:00