Skip to content

Commit

Permalink
Build: (029bcb1) Update doc authoring guideline
Browse files Browse the repository at this point in the history
  • Loading branch information
@jhrv
jhrv committed Feb 7, 2024
1 parent 4c56b12 commit 4c805c3
Show file tree
Hide file tree
Showing 3 changed files with 159 additions and 15 deletions.
2 changes: 1 addition & 1 deletion search/search_index.json
View file

Large diffs are not rendered by default.

Binary file modified sitemap.xml.gz
View file
Binary file not shown.
172 changes: 158 additions & 14 deletions technical/write-the-doc/write-the-doc/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@
<div data-md-component="skip">


<a href="#nais-doc-authoring-guide" class="md-skip">
<a href="#authoring-nais-docs" class="md-skip">
Skip to content
</a>

Expand Down Expand Up @@ -598,19 +598,73 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>

<li class="md-nav__item">
<a href="#nais-doc-authoring-guide" class="md-nav__link">
<a href="#authoring-nais-docs" class="md-nav__link">
<span class="md-ellipsis">
NAIS Doc authoring guide
Authoring NAIS-docs
</span>
</a>

<nav class="md-nav" aria-label="NAIS Doc authoring guide">
</li>

<li class="md-nav__item">
<a href="#diataxis" class="md-nav__link">
<span class="md-ellipsis">
Diataxis
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#conventions" class="md-nav__link">
<span class="md-ellipsis">
Conventions
</span>
</a>

<nav class="md-nav" aria-label="Conventions">
<ul class="md-nav__list">

<li class="md-nav__item">
<a href="#diataxis-identifies-four-distinct-needs-and-four-corresponding-forms-of-documentation-tutorials-how-to-guides-technical-reference-and-explanation-it-places-them-in-a-systematic-relationship-and-proposes-that-documentation-should-itself-be-organised-around-the-structures-of-those-needs" class="md-nav__link">
<a href="#documentation-structure" class="md-nav__link">
<span class="md-ellipsis">
Documentation structure
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#placeholder-variables" class="md-nav__link">
<span class="md-ellipsis">
Placeholder variables
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#tenant-variables" class="md-nav__link">
<span class="md-ellipsis">
Tenant variables
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#code-blocks" class="md-nav__link">
<span class="md-ellipsis">
Code blocks
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#alternate-paths" class="md-nav__link">
<span class="md-ellipsis">
Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs.
Alternate paths
</span>
</a>

Expand Down Expand Up @@ -777,19 +831,73 @@
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>

<li class="md-nav__item">
<a href="#nais-doc-authoring-guide" class="md-nav__link">
<a href="#authoring-nais-docs" class="md-nav__link">
<span class="md-ellipsis">
NAIS Doc authoring guide
Authoring NAIS-docs
</span>
</a>

<nav class="md-nav" aria-label="NAIS Doc authoring guide">
</li>

<li class="md-nav__item">
<a href="#diataxis" class="md-nav__link">
<span class="md-ellipsis">
Diataxis
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#conventions" class="md-nav__link">
<span class="md-ellipsis">
Conventions
</span>
</a>

<nav class="md-nav" aria-label="Conventions">
<ul class="md-nav__list">

<li class="md-nav__item">
<a href="#diataxis-identifies-four-distinct-needs-and-four-corresponding-forms-of-documentation-tutorials-how-to-guides-technical-reference-and-explanation-it-places-them-in-a-systematic-relationship-and-proposes-that-documentation-should-itself-be-organised-around-the-structures-of-those-needs" class="md-nav__link">
<a href="#documentation-structure" class="md-nav__link">
<span class="md-ellipsis">
Documentation structure
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#placeholder-variables" class="md-nav__link">
<span class="md-ellipsis">
Placeholder variables
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#tenant-variables" class="md-nav__link">
<span class="md-ellipsis">
Tenant variables
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#code-blocks" class="md-nav__link">
<span class="md-ellipsis">
Code blocks
</span>
</a>

</li>

<li class="md-nav__item">
<a href="#alternate-paths" class="md-nav__link">
<span class="md-ellipsis">
Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs.
Alternate paths
</span>
</a>

Expand Down Expand Up @@ -820,9 +928,16 @@

<h1>Write the doc</h1>

<h3 id="nais-doc-authoring-guide">NAIS Doc authoring guide<a class="headerlink" href="#nais-doc-authoring-guide" title="Permanent link">&para;</a></h3>
<p>This guide is a highly compressed summary of the doc theory published at <a href="https://diataxis.fr/">Diataxis</a></p>
<h4 id="diataxis-identifies-four-distinct-needs-and-four-corresponding-forms-of-documentation-tutorials-how-to-guides-technical-reference-and-explanation-it-places-them-in-a-systematic-relationship-and-proposes-that-documentation-should-itself-be-organised-around-the-structures-of-those-needs"><em>Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs.</em><a class="headerlink" href="#diataxis-identifies-four-distinct-needs-and-four-corresponding-forms-of-documentation-tutorials-how-to-guides-technical-reference-and-explanation-it-places-them-in-a-systematic-relationship-and-proposes-that-documentation-should-itself-be-organised-around-the-structures-of-those-needs" title="Permanent link">&para;</a></h4>
<h3 id="authoring-nais-docs">Authoring NAIS-docs<a class="headerlink" href="#authoring-nais-docs" title="Permanent link">&para;</a></h3>
<p>When writing <a href="https://github.com/nais/doc">the documentation</a> we serve at doc.nais.io/doc.<tenant>.cloud.nais.io, we want to make sure that the content we provide helps our users to understand and use the platform we're making.</p>
<p>Some key points to keep in mind when writing the docs is:
- <a href="#diataxishttpsdiataxisfr">Following the diataxis theory</a>
- Less is more: Keep it short and to the point. This makes it easier to sustain high quality over time.
- We are writing docs for the <em>users</em> of our platform. No one else. We should be empathetic to their needs and understanding of the platform, and be mindful of adding details that are not relevant in the current documentation context
- <a href="#conventions">Consistency</a> in style and tone
- NAIS <a href="https://diataxis.fr/quality/">Quality</a></p>
<h2 id="diataxis"><a href="https://diataxis.fr/">Diataxis</a><a class="headerlink" href="#diataxis" title="Permanent link">&para;</a></h2>
<p><em>Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs.</em></p>
<p>To create contents you must determine what you are setting out to do. Are you writing a <em>Tutorial</em>, a <em>How-to guide</em>, a <em>Reference</em> or is it a comprehensive <em>Explanantion</em> of a concept.</p>
<ul>
<li><a href="https://diataxis.fr/tutorials/"><strong>Tutorial</strong></a><ul>
Expand All @@ -846,6 +961,35 @@ <h4 id="diataxis-identifies-four-distinct-needs-and-four-corresponding-forms-of-
</ul>
</li>
</ul>
<h2 id="conventions">Conventions<a class="headerlink" href="#conventions" title="Permanent link">&para;</a></h2>
<h3 id="documentation-structure">Documentation structure<a class="headerlink" href="#documentation-structure" title="Permanent link">&para;</a></h3>
<p>The file tree represents the structure of the navigation menu.
The H1 (#) will be the title of the page and the title in the navigation menu</p>
<p>To override the placement in the navigation menu, we use the <a href="https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/">Awesome Pages plugin</a> for MkDocs.</p>
<h3 id="placeholder-variables">Placeholder variables<a class="headerlink" href="#placeholder-variables" title="Permanent link">&para;</a></h3>
<p>Where the reader is expected to change the content, we use placeholder variables.
These variables are written in uppercase, with words separated by hyphens, surrounded by &lt;&gt;. For example: <code>&lt;MY-APP&gt;</code>.</p>
<h3 id="tenant-variables">Tenant variables<a class="headerlink" href="#tenant-variables" title="Permanent link">&para;</a></h3>
<p>We template the tenant name in the documentation using &lt;<tenant()>&gt;
When the documentation is built, this will be replaced with the relevant tenant name.</p>
<h3 id="code-blocks">Code blocks<a class="headerlink" href="#code-blocks" title="Permanent link">&para;</a></h3>
<p>We want to use expanded notes with the filename in the title and the code block inside the note. Preferably with syntax highlighting where applicable.
This will give the reader a copy button with the relevant code and the filename will be visible in the navigation menu.</p>
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>???+ note &quot;.nais/app.yaml&quot;
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a> ```yaml hl_lines=&quot;6-8 11&quot;
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a> apiVersion: nais.io/v1alpha1
<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a> kind: Application
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a> ...
<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a> ```
</code></pre></div>
<h3 id="alternate-paths">Alternate paths<a class="headerlink" href="#alternate-paths" title="Permanent link">&para;</a></h3>
<p>When the user is given a choice, we want to show both paths in the documentation. For example programming language, OS or different methods</p>
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a> === &quot;Linux&quot;
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a> linux specific stuff
<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a> === &quot;macOS&quot;
<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a> macOS specific stuff
</code></pre></div>



Expand Down

0 comments on commit 4c805c3

Please sign in to comment.