software documentation that thing we love to...
TRANSCRIPT
SOFTWARE DOCUMENTATIONTHAT THINGWE LOVE TO HATE
Ludovic CourtesService d’experimentation & developpementInria Bordeaux Sud-Ouest
19 June 2012
introduction
soothing the developer’s conscience
meeting the user’s expectations
tools for doc
outro
L. Courtes — Software Documentation—That Thing We Love to Hate 2
user...
L. Courtes — Software Documentation—That Thing We Love to Hate 3
http://xkcd.com/293/
user vs. developer
L. Courtes — Software Documentation—That Thing We Love to Hate 4
introduction
soothing the developer’s conscience
meeting the user’s expectations
tools for doc
outro
L. Courtes — Software Documentation—That Thing We Love to Hate 5
lazy developer’s great idea #0
“Let’s get this intern to scribble a web page!”
L. Courtes — Software Documentation—That Thing We Love to Hate 6
lazy developer’s great idea #0
“Let’s get this intern to scribble a web page!”
L. Courtes — Software Documentation—That Thing We Love to Hate 7
lazy developer’s great idea #1
“We’ll setup a wiki, and let users write their doc”
“Great, and don’t forget a link to Bob’s web page.”
L. Courtes — Software Documentation—That Thing We Love to Hate 8
lazy developer’s great idea #1
“We’ll setup a wiki, and let users write their doc”“Great, and don’t forget a link to Bob’s web page.”
L. Courtes — Software Documentation—That Thing We Love to Hate 9
lazy developer’s great idea #1
L. Courtes — Software Documentation—That Thing We Love to Hate 10
lazy developer’s great idea #2
“Let’s generate doc and be done with it!”
“Best of all: it’ll be consistent with the code!”
L. Courtes — Software Documentation—That Thing We Love to Hate 11
lazy developer’s great idea #2
“Let’s generate doc and be done with it!”
“Best of all: it’ll be consistent with the code!”
L. Courtes — Software Documentation—That Thing We Love to Hate 12
lazy developer’s great idea #2
L. Courtes — Software Documentation—That Thing We Love to Hate 13
lazy developer’s great idea #2
L. Courtes — Software Documentation—That Thing We Love to Hate 14
lazy developer’s great idea #2
L. Courtes — Software Documentation—That Thing We Love to Hate 15
lazy developer’s great idea #2
L. Courtes — Software Documentation—That Thing We Love to Hate 16
bird’s eye view?
lazy developer’s great idea #2
L. Courtes — Software Documentation—That Thing We Love to Hate 17
bird’s eye view?
code structure vs. conceptual structure
smart developer’s idea: combine all previous ideas!
“We’ll get a fee for the real doc, give away theauto-generated stuff, and let users write the rest.”
L. Courtes — Software Documentation—That Thing We Love to Hate 18
smart developer’s idea: combine all previous ideas!
L. Courtes — Software Documentation—That Thing We Love to Hate 19
smart developer’s idea: combine all previous ideas!
L. Courtes — Software Documentation—That Thing We Love to Hate 20
“If you want them to RTFM,make a better FM.”
— unknown author
L. Courtes — Software Documentation—That Thing We Love to Hate 21
introduction
soothing the developer’s conscience
meeting the user’s expectations
tools for doc
outro
L. Courtes — Software Documentation—That Thing We Love to Hate 22
contents
L. Courtes — Software Documentation—That Thing We Love to Hate 23
provide context & motivation
L. Courtes — Software Documentation—That Thing We Love to Hate 24
provide context & motivation
L. Courtes — Software Documentation—That Thing We Love to Hate 25
give examples to... help get started
L. Courtes — Software Documentation—That Thing We Love to Hate 26
give examples to... illustrate concepts
L. Courtes — Software Documentation—That Thing We Love to Hate 27
give examples to... illustrate functions
L. Courtes — Software Documentation—That Thing We Love to Hate 28
reference doc calls for rigorous wording
L. Courtes — Software Documentation—That Thing We Love to Hate 29
reference doc calls for rigorous wording
L. Courtes — Software Documentation—That Thing We Love to Hate 30
?
reference doc calls for rigorous wording
L. Courtes — Software Documentation—That Thing We Love to Hate 31
reference doc calls for rigorous wording
L. Courtes — Software Documentation—That Thing We Love to Hate 32
form
L. Courtes — Software Documentation—That Thing We Love to Hate 33
use consistent vocabulary & typographical conventions
L. Courtes — Software Documentation—That Thing We Love to Hate 34
use consistent vocabulary & typographical conventions
L. Courtes — Software Documentation—That Thing We Love to Hate 35
don’t be needlessly verbose
L. Courtes — Software Documentation—That Thing We Love to Hate 36
don’t be needlessly verbose
L. Courtes — Software Documentation—That Thing We Love to Hate 37
use (hyper)links to concepts, and indexes
L. Courtes — Software Documentation—That Thing We Love to Hate 38
use (hyper)links to concepts, and indexes
L. Courtes — Software Documentation—That Thing We Love to Hate 39
use (hyper)links to concepts, and indexes
L. Courtes — Software Documentation—That Thing We Love to Hate 40
media
L. Courtes — Software Documentation—That Thing We Love to Hate 41
media
L. Courtes — Software Documentation—That Thing We Love to Hate 42
media
L. Courtes — Software Documentation—That Thing We Love to Hate 43
media
L. Courtes — Software Documentation—That Thing We Love to Hate 44
;
introduction
soothing the developer’s conscience
meeting the user’s expectations
tools for doc
outro
L. Courtes — Software Documentation—That Thing We Love to Hate 45
LibreOffice, OpenOffice, & co.
L. Courtes — Software Documentation—That Thing We Love to Hate 46
LibreOffice, OpenOffice, & co.
L. Courtes — Software Documentation—That Thing We Love to Hate 47
are you serious?!
LibreOffice, OpenOffice, & co.
L. Courtes — Software Documentation—That Thing We Love to Hate 48
mixed form/content concernsno or distinct versioning
uglyhard to collaborate
hardly consistent typographical conventions
paper-only
Unix man pages
L. Courtes — Software Documentation—That Thing We Love to Hate 49
Unix man pages
L. Courtes — Software Documentation—That Thing We Love to Hate 50
no structure
no indices
no hyperlinks
Unix man pages
L. Courtes — Software Documentation—That Thing We Love to Hate 51
no structure
no indices
no hyperlinks
ssh(1): 800 lines OpenSSL: 1,170 pages in Sect. 3
Doxygen: its evil rootshttp://doxygen.org/
#ifndef HWLOC_BITMAP_H
#define HWLOC_BITMAP_H
/** \defgroup hwlocality_bitmap The bitmap API
*
* The ::hwloc_bitmap_t type represents a set of objects.
* @{
*/
/** \brief Free bitmap \p bitmap.
*
* If \p bitmap is \c NULL, no operation is performed.
*/
void hwloc_bitmap_free(hwloc_bitmap_t bitmap);
L. Courtes — Software Documentation—That Thing We Love to Hate 52
mixed comment/markup
Doxygen: pushing the limitsdoxy files
namespace Eigen {
/** \page TopicAliasing Aliasing
Statements like <tt>mat = 2 * mat;</tt> or
<tt>mat = mat.transpose();</tt> exhibit aliasing.
<b>Table of contents</b>
- \ref TopicAliasingExamples
- \ref TopicAliasingSolution
\section TopicAliasingExamples Examples
Here is a simple example exhibiting aliasing:
<table class="example">
<tr><th>Example</th><th>Output</th></tr>
<tr><td>
\include TopicAliasing_block.cpp
</td>
<td>
\verbinclude TopicAliasing_block.out
</td></tr></table>
L. Courtes — Software Documentation—That Thing We Love to Hate 53
Doxygen: pushing the limitsdoxy files
namespace Eigen {
/** \page TopicAliasing Aliasing
Statements like <tt>mat = 2 * mat;</tt> or
<tt>mat = mat.transpose();</tt> exhibit aliasing.
<b>Table of contents</b>
- \ref TopicAliasingExamples
- \ref TopicAliasingSolution
\section TopicAliasingExamples Examples
Here is a simple example exhibiting aliasing:
<table class="example">
<tr><th>Example</th><th>Output</th></tr>
<tr><td>
\include TopicAliasing_block.cpp
</td>
<td>
\verbinclude TopicAliasing_block.out
</td></tr></table>
L. Courtes — Software Documentation—That Thing We Love to Hate 54
C++, HTML, andLATEX all mixed up!
Doxygen: pushing the limitsdoxy files
namespace Eigen {
/** \page TopicAliasing Aliasing
Statements like <tt>mat = 2 * mat;</tt> or
<tt>mat = mat.transpose();</tt> exhibit aliasing.
<b>Table of contents</b>
- \ref TopicAliasingExamples
- \ref TopicAliasingSolution
\section TopicAliasingExamples Examples
Here is a simple example exhibiting aliasing:
<table class="example">
<tr><th>Example</th><th>Output</th></tr>
<tr><td>
\include TopicAliasing_block.cpp
</td>
<td>
\verbinclude TopicAliasing_block.out
</td></tr></table>
L. Courtes — Software Documentation—That Thing We Love to Hate 55
C++, HTML, andLATEX all mixed up!
and yet it works!
Doxygen: pushing the limitsdoxy files
namespace Eigen {
/** \page TopicAliasing Aliasing
Statements like <tt>mat = 2 * mat;</tt> or
<tt>mat = mat.transpose();</tt> exhibit aliasing.
<b>Table of contents</b>
- \ref TopicAliasingExamples
- \ref TopicAliasingSolution
\section TopicAliasingExamples Examples
Here is a simple example exhibiting aliasing:
<table class="example">
<tr><th>Example</th><th>Output</th></tr>
<tr><td>
\include TopicAliasing_block.cpp
</td>
<td>
\verbinclude TopicAliasing_block.out
</td></tr></table>
L. Courtes — Software Documentation—That Thing We Love to Hate 56
LATEX, a false good ideahttp://www.latex-project.org/
L. Courtes — Software Documentation—That Thing We Love to Hate 57
LATEX, a false good ideahttp://www.latex-project.org/
L. Courtes — Software Documentation—That Thing We Love to Hate 58
paper-only*
* HeVeA & co., sure, but heavy use of latexonly, ifhtml, etc.
LATEX, a false good ideahttp://www.latex-project.org/
L. Courtes — Software Documentation—That Thing We Love to Hate 59
paper-only*
no medium-neutral, inter-manual cross-refs
* HeVeA & co., sure, but heavy use of latexonly, ifhtml, etc.
LATEX, a false good ideahttp://www.latex-project.org/
\begin{ocamldoccode}
type int
\end{ocamldoccode}
\index{int@\verb‘int‘}
\begin{ocamldocdescription}
The type of integer numbers.
\end{ocamldocdescription}
\begin{ocamldoccode}
exception End_of_file
\end{ocamldoccode}
\index{Endoffile@\verb‘End_of_file‘}
\begin{ocamldocdescription}
Exception raised by input functions to signal that the
end of file has been reached.
\end{ocamldocdescription}
L. Courtes — Software Documentation—That Thing We Love to Hate 60
LATEX, a false good ideahttp://www.latex-project.org/
\begin{ocamldoccode}
type int
\end{ocamldoccode}
\index{int@\verb‘int‘}
\begin{ocamldocdescription}
The type of integer numbers.
\end{ocamldocdescription}
\begin{ocamldoccode}
exception End_of_file
\end{ocamldoccode}
\index{Endoffile@\verb‘End_of_file‘}
\begin{ocamldocdescription}
Exception raised by input functions to signal that the
end of file has been reached.
\end{ocamldocdescription}
L. Courtes — Software Documentation—That Thing We Love to Hate 61
no API-oriented markup
LATEX, a false good ideahttp://www.latex-project.org/
\begin{ocamldoccode}
type int
\end{ocamldoccode}
\index{int@\verb‘int‘}
\begin{ocamldocdescription}
The type of integer numbers.
\end{ocamldocdescription}
\begin{ocamldoccode}
exception End_of_file
\end{ocamldoccode}
\index{Endoffile@\verb‘End_of_file‘}
\begin{ocamldocdescription}
Exception raised by input functions to signal that the
end of file has been reached.
\end{ocamldocdescription}
L. Courtes — Software Documentation—That Thing We Love to Hate 62
no API-oriented markup
do it yourself!
DocBookhttp://docbook.org/
L. Courtes — Software Documentation—That Thing We Love to Hate 63
DocBookhttp://docbook.org/
L. Courtes — Software Documentation—That Thing We Love to Hate 64
DocBookhttp://docbook.org/
L. Courtes — Software Documentation—That Thing We Love to Hate 65
medium-independent!
DocBook markup
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude">
<info>
<title>User’s Guide</title>
<edition>Version 4.2</edition>
<author>
<personname>
<firstname>Bob</firstname>
<surname>Smith</surname>
</personname>
<affiliation>
<orgname>Foobar, Inc.</orgname>
</affiliation>
<contrib>Author</contrib>
</author>
<date>June 2012</date>
</info>
L. Courtes — Software Documentation—That Thing We Love to Hate 66
DocBook markup
<section><title>The Nix expression</title>
<example xml:id=’ex’><title>Nix expression for GNU Hello
(<textpos>default.nix</filename>)</title>
<programlisting>
{ stdenv, fetchurl, perl }: <co xml:id=’ex-co1’ />
stdenv.mkDerivation { <co xml:id=’ex-co2’ />
...
} </programlisting>
</example>
<para><xref linkend=’ex’ /> shows an expression for
GNU Hello. It’s actually already in the Packages
collection in <filename>hello/ex-1/default.nix</filename>.
L. Courtes — Software Documentation—That Thing We Love to Hate 67
DocBook markup
<section><title>The Nix expression</title>
<example xml:id=’ex’><title>Nix expression for GNU Hello
(<textpos>default.nix</filename>)</title>
<programlisting>
{ stdenv, fetchurl, perl }: <co xml:id=’ex-co1’ />
stdenv.mkDerivation { <co xml:id=’ex-co2’ />
...
} </programlisting>
</example>
<para><xref linkend=’ex’ /> shows an expression for
GNU Hello. It’s actually already in the Packages
collection in <filename>hello/ex-1/default.nix</filename>.
L. Courtes — Software Documentation—That Thing We Love to Hate 68
high-level markup!
focus on content!
DocBook tool chain
$ xsltproc --param html.stylesheet ’style.css’ \
--param callout.graphics.extension ’.gif’ \
--nonet --xinclude \
--output manual.html \
/path/to/docbook.xsl manual.xml
$ dblatex manual.xml
L. Courtes — Software Documentation—That Thing We Love to Hate 69
DocBook tool chain
$ xsltproc --param html.stylesheet ’style.css’ \
--param callout.graphics.extension ’.gif’ \
--nonet --xinclude \
--output manual.html \
/path/to/docbook.xsl manual.xml
$ dblatex manual.xml
L. Courtes — Software Documentation—That Thing We Love to Hate 70
GNU Texinfohttp://gnu.org/software/texinfo/
L. Courtes — Software Documentation—That Thing We Love to Hate 71
GNU Texinfo markup
@node Foreign Function Interface
@section Foreign Function Interface
@cindex foreign function interface
@cindex ffi
The more one hacks in Scheme, the more one realizes
that there are actually two computational worlds: one
which is warm and alive, that land of parentheses, and
one cold and dead, the land of C and its ilk.
@menu
* Foreign Libraries:: Dynamic linking.
* Foreign Functions:: Simple calls to C procedures.
* C Extensions:: Extending Guile in C.
...@end menu
L. Courtes — Software Documentation—That Thing We Love to Hate 72
GNU Texinfo markup
@node Foreign Function Interface
@section Foreign Function Interface
@cindex foreign function interface
@cindex ffi
The more one hacks in Scheme, the more one realizes
that there are actually two computational worlds: one
which is warm and alive, that land of parentheses, and
one cold and dead, the land of C and its ilk.
@menu
* Foreign Libraries:: Dynamic linking.
* Foreign Functions:: Simple calls to C procedures.
* C Extensions:: Extending Guile in C.
...@end menu
L. Courtes — Software Documentation—That Thing We Love to Hate 73
for the HTML/Info output
GNU Texinfo specific markup
@deffn {Scheme Procedure} bytevector-length @var{bv}
@deffnx {C Function} scm bytevector length (@var{bv})
Return the length in bytes of bytevector @var{bv}.
@end deffn
@deftypefun size t scm c bytevector length (SCM @var{bv})
Likewise, return the length in bytes of bytevector @var{bv}.
@end deftypefn
L. Courtes — Software Documentation—That Thing We Love to Hate 74
functions
GNU Texinfo specific markup
@deftp {Data Type} {struct starpu_data_filter}
The filter structure describes a data partitioning operation,
to be given to the @code{starpu_data_partition} function,
see @ref{starpu_data_partition} for an example.
The fields are:
@table @asis
@item @code{unsigned nchildren}
Number of parts to partition the data into.
@item @code{void *filter_arg_ptr}
Additional pointer parameter for the filter
function, such as the sizes of the different parts.
@end table
@end deftp
L. Courtes — Software Documentation—That Thing We Love to Hate 75
data types
GNU Texinfo specific markup
@deftp {Data Type} {struct starpu_data_filter}
The filter structure describes a data partitioning operation,
to be given to the @code{starpu_data_partition} function,
see @ref{starpu_data_partition} for an example.
The fields are:
@table @asis
@item @code{unsigned nchildren}
Number of parts to partition the data into.
@item @code{void *filter_arg_ptr}
Additional pointer parameter for the filter
function, such as the sizes of the different parts.
@end table
@end deftp
L. Courtes — Software Documentation—That Thing We Love to Hate 76
GNU Texinfo tool chain
$ makeinfo manual.texi
$ makeinfo --plaintext manual.texi
$ makeinfo --html --css-ref=style.css
manual.texi
$ texi2pdf -I /path/to/texinfo.tex manual.texi
L. Courtes — Software Documentation—That Thing We Love to Hate 77
GNU Texinfo tool chain
$ makeinfo manual.texi
$ makeinfo --plaintext manual.texi
$ makeinfo --html --css-ref=style.css
manual.texi
$ texi2pdf -I /path/to/texinfo.tex manual.texi
L. Courtes — Software Documentation—That Thing We Love to Hate 78
GNU Texinfo tool chain
$ makeinfo manual.texi
$ makeinfo --plaintext manual.texi
$ makeinfo --html --css-ref=style.css
manual.texi
$ texi2pdf -I /path/to/texinfo.tex manual.texi
L. Courtes — Software Documentation—That Thing We Love to Hate 79
other tools worth a look
I Org-Mode + Babel, http://orgmode.org/
I AsciiDoc, http://www.methods.co.nz/asciidoc/
I reStructuredText (Python), http://docutils.sf.net/
I Sphinx (Python), http://sphinx.pocoo.org/
I Skribe (Scheme),http://www-sop.inria.fr/mimosa/fp/Skribe/
I Skribilo (Scheme), http://nongnu.org/skribilo/
I ...
L. Courtes — Software Documentation—That Thing We Love to Hate 80
introduction
soothing the developer’s conscience
meeting the user’s expectations
tools for doc
outro
L. Courtes — Software Documentation—That Thing We Love to Hate 81
summary
I auto-extracted doc is (usually) an insult to users
I doc structure must follow human reasoning
I use tools that separate presentation & content
L. Courtes — Software Documentation—That Thing We Love to Hate 82
summary
I auto-extracted doc is (usually) an insult to users
I doc structure must follow human reasoning
I use tools that separate presentation & content
L. Courtes — Software Documentation—That Thing We Love to Hate 83
summary
I auto-extracted doc is (usually) an insult to users
I doc structure must follow human reasoning
I use tools that separate presentation & content
L. Courtes — Software Documentation—That Thing We Love to Hate 84
worthy readings
I “GNOME Documentation Style Guide V1.6”,http://developer.gnome.org/gdp-style-guide/
I “GNU Coding Standards”,http://gnu.org/prep/standards/standards.html