<p><spanclass="sc"><abbrtitle="Too long; didn't read">tl;dr</abbr>: </span> Some hints on how to make great documentation for Haskell libraries.</p>
<oltype="1">
<li>Create a <code>Tutorial</code> module containing nothing except documentation.</li>
<li>Mention the <code>Tutorial</code> module in your <code>cabal</code> description</li>
<li>Use <code>doctest</code> to check your documentation is up to date</li>
<li>For more complex real world examples, link to the source of some test.</li>
</ol>
</div>
<p>Great documentation make a big difference. A bad documentation could simply make people not using your lib.</p>
<p>My friend was learning Haskell. To start he tried a Haskell library to make a small application. The documentation was deprecated to the point he wasn’t able to make a basic example work. How do you believe he felt? What does he thought about Haskell in general?</p>
<p>So here are my hint on how to make a great documentation in Haskell.</p>
<p>Documentation can take many different form.</p>
<oltype="1">
<li><strong>Tutorials/Guides</strong>– write some prose which friendly take a user by hand and help him</li>
<li><strong>Examples</strong>– how to use each function</li>
<li><strong>Generated API Documentation</strong>– haddock</li>
</ol>
<h2id="hints">Hints</h2>
<h3id="tutorialsguides">Tutorials/Guides</h3>
<oltype="1">
<li>Create a new module named <code>Tutorial</code> (or <code>Guide.GuideTopic</code>)</li>
<li>Create a link to the tutorial in the cabal description</li>
<li>Create a link to the tutorial in your README</li>
<li>Here is an example some <code>Tutorial</code> module content:</li>
<p>To prevent obsolescence of your tutorial, use <code>doctest</code>.</p>
<p>That way when you’ll do a <code>stack test</code> or <code>cabal test</code> you’ll get errors if some example doesn’t work anymore.</p>
<h3id="examples-doctest">Examples (doctest)</h3>
<p><code>doctest</code> is a great way to provide examples in your code documentation. These example will then be used as tests. Apparently it comes from Python community.</p>
<p>To use <code>doctest</code>, this is very simple:</p>
<divclass="sourceCode"id="cb2"><preclass="sourceCode haskell"><codeclass="sourceCode haskell"><aclass="sourceLine"id="cb2-1"title="1"><spanclass="co">-- | My function description</span></a>
<p>There are plenty of alternative solution. I provide the one I believe would be used by most people. So if you use <code>github</code> simply create an account on <ahref="http://travis-ci.org"><code>travis</code></a>.</p>
<p>Add a <code>.travis.yml</code> file in your repo containing the content of the file <ahref="http://docs.haskellstack.org/en/stable/GUIDE/#travis-with-caching">here</a> and remove the builds you don’t need. It will build your project using a lot of different GHC versions and environemnts.</p>
<p>If you are afraid by such its complexity you might just want to use this one:</p>
<p>If you didn’t declared your package to <code>stackage</code>, please do it. It isn’t much work. Just edit a file to add your package. And you’ll could be able to add another badge:</p>
<divclass="sourceCode"id="cb9"><preclass="sourceCode .markdown"><codeclass="sourceCode markdown"><aclass="sourceLine"id="cb9-1"title="1"><spanclass="ot">[![packagename on Stackage LTS](http://stackage.org/package/packagename/badge/lts-3)</span>](http://stackage.org/lts/package/packagename)</a></code></pre></div>
<p>See <ahref="https://www.fpcomplete.com/blog/2015/10/stackage-badges">Stackage Badges</a> for more informations.</p>
<h3id="creating-a-new-project-with-stack">Creating a new project with <code>stack</code></h3>
<p>If you use <code>stack</code> I suggest you to use the <code>tasty-travis</code> template. It will include the boilerplate for:</p>
<ul>
<li>tests</li>
<li>doctest</li>
<li>benchmark</li>
<li>travis CI</li>
<li>a README file to help you start</li>
</ul>
<p>So edit your <code>~/.stack/config.yaml</code> like this:</p>
<pre><code>templates:
params:
author-name: Your Name
author-email: your@mail.com
copyright: 'Copyright: (c) 2016 Your Name'
github-username: yourusername
category: Development</code></pre>
<p>And then you can create a new projec with:</p>
<pre><code>stack new my-project tasty-travis</code></pre>
= C { a :: TypeA <spanclass="highlight">-- ^ field a description</span>
, b :: TypeB <spanclass="highlight">-- ^ field b description</span>
}</code></pre>
<p><strong>Module</strong>:</p>
<pre><code>{-|
Module : MyModule
Description: Short description
Copyright : (c)
License : MIT
Here is a longer description of this module.
With some code symbol @MyType@.
And also a block of code:
@
data MyData = C Int Int
myFunction :: MyData -> Int
@
-}</code></pre>
<p><strong>Documentation Structure</strong>:</p>
<pre><code>module MyModule (
-- * Classes
C(..),
-- * Types
-- ** A data type
T,
-- ** A record
R,
-- * Some functions
f, g
) where</code></pre>
<p>That will generate headings.</p>
<h2id="other-random-ideas">Other Random Ideas</h2>
<p>In Haskell we have great tools like <ahref="http://hayoo.fh-wedel.de"><code>hayoo!</code></a> and <ahref="https://www.haskell.org/hoogle/"><code>hoogle</code></a>.</p>
<p>And <code>hackage</code> and <code>stackage</code> provide also a lot of informations.</p>
<p>But generally we lack a lot of Tutorials and Guides. This post was an attempt to help people making more of them.</p>
<p>But there are other good ideas to help improve the situation.</p>
<h3id="create-a-doc-with-link-to-best-practices">Create a doc with link to best practices</h3>
<p>In clojure when you create a new project using <code>lein new my-project</code> a directory <code>doc</code> is created for you. It contains a file with a link to this blog post:</p>
<ul>
<li><ahref="https://jacobian.org/writing/what-to-write/">What to write</a></li>
</ul>
<h3id="having-a-page-by-functionsymbol-with-comments">Having a page by function/symbol with comments</h3>
<p>If you try to search for some clojure function on a search engine there is a big chance the first result will link to:</p>
<ul>
<li><ahref="http://clojuredocs.org"><code>clojuredocs.org</code></a>: try to search for <code>reduce</code>, <code>update-in</code> or <code>index</code> for example</li>
</ul>
<p>For each symbol necessiting a documentation. You don’t only have the details and standard documentation. You’ll also get:</p>
<ul>
<li>Responsive Design (sometime you want to look at documentation on a mobile)</li>
<li>Contributed Examples</li>
<li>Contributed See Also section</li>
<li>Contributed notes/comments</li>
</ul>
<p><ahref="http://clojuredocs.org"><code>clojuredocs.org</code></a> is an independant website from the official Clojure website.</p>
<p>Most of the time, if you google the function you search you end up on <ahref="http://clojuredocs.org">clojuredocs</a> for wich there are many contributions.</p>
<p>Currently stackage is closer to these feature than hackage. Because on stackage you have access to the README and also some comments by package.</p>
<p>I believe it would be more efficient to have at least a page by module and why not a page by <em>symbol</em> (data, functions, typeclasses…).</p>
<p>For example, we could provide details about <code>foldl</code> for example. Also as there would be less information to display, it will make the design cleaner.</p>
<p>Today, if you want to help documenting, you need to make a PR to the source of some library. While if we had an equivalent to clojuredocs for Haskell, adding documentation would simply be a few clicks away:</p>
<oltype="1">
<li>login</li>
<li>add/edit some example, comments, see-also section</li>
</ol>
<p>There are more than 23k people on <code>/r/haskell</code>. If only 1% of them would take 10 minutes adding a bit of documentation it will certainly change a lot of things in the percieved documentation quality.</p>
<p>And last but not least,</p>
<h2id="design-is-important"><strong>Design is important</strong></h2>
<div>
<imgsrc="../../../../Scratch/img/blog/Haskell-Tutorials--a-tutorial/design_is_important.jpg"alt="Design is Important"/>
</div>
<p>Design is a vague word. A good design should care not only about how something look, but also how users will interact with it. For example by removing things to focus on the essential.</p>
<p>When I stumble upon some random blog post or random specification in the Haskell community, I had too much a feeling of old fashioned design.</p>
<p>If you look at node.js community lot of their web page look cleaner, easier to read and in the end, more user friendly.</p>
<p>Haskell is very different from node, I wouldn’t like to replace all long and precise documentation with short human unprecise concepts. I don’t want to transform scientific papers by tweets.</p>
<p>But like the scientific community has upgraded with the use of LaTeX, I believe we could find something similar that would make, very clean environment for most of us. A kind of look and feel that will be</p>
<ul>
<li>modern</li>
<li>device friendly (either on computer, mobile, tablet)</li>
<li>efficient, focus on what is most important and is helpful</li>