![Page 1: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/1.jpg)
SOFTWARE DOCUMENTATIONTHAT THINGWE LOVE TO HATE
Ludovic CourtesService d’experimentation & developpementInria Bordeaux Sud-Ouest
19 June 2012
![Page 2: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/2.jpg)
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
![Page 3: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/3.jpg)
user...
L. Courtes — Software Documentation—That Thing We Love to Hate 3
http://xkcd.com/293/
![Page 4: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/4.jpg)
user vs. developer
L. Courtes — Software Documentation—That Thing We Love to Hate 4
![Page 5: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/5.jpg)
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
![Page 6: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/6.jpg)
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
![Page 7: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/7.jpg)
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
![Page 8: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/8.jpg)
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
![Page 9: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/9.jpg)
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
![Page 10: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/10.jpg)
lazy developer’s great idea #1
L. Courtes — Software Documentation—That Thing We Love to Hate 10
![Page 11: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/11.jpg)
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
![Page 12: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/12.jpg)
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
![Page 13: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/13.jpg)
lazy developer’s great idea #2
L. Courtes — Software Documentation—That Thing We Love to Hate 13
![Page 14: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/14.jpg)
lazy developer’s great idea #2
L. Courtes — Software Documentation—That Thing We Love to Hate 14
![Page 15: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/15.jpg)
lazy developer’s great idea #2
L. Courtes — Software Documentation—That Thing We Love to Hate 15
![Page 16: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/16.jpg)
lazy developer’s great idea #2
L. Courtes — Software Documentation—That Thing We Love to Hate 16
bird’s eye view?
![Page 17: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/17.jpg)
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
![Page 18: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/18.jpg)
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
![Page 19: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/19.jpg)
smart developer’s idea: combine all previous ideas!
L. Courtes — Software Documentation—That Thing We Love to Hate 19
![Page 20: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/20.jpg)
smart developer’s idea: combine all previous ideas!
L. Courtes — Software Documentation—That Thing We Love to Hate 20
![Page 21: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/21.jpg)
“If you want them to RTFM,make a better FM.”
— unknown author
L. Courtes — Software Documentation—That Thing We Love to Hate 21
![Page 22: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/22.jpg)
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
![Page 23: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/23.jpg)
contents
L. Courtes — Software Documentation—That Thing We Love to Hate 23
![Page 24: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/24.jpg)
provide context & motivation
L. Courtes — Software Documentation—That Thing We Love to Hate 24
![Page 25: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/25.jpg)
provide context & motivation
L. Courtes — Software Documentation—That Thing We Love to Hate 25
![Page 26: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/26.jpg)
give examples to... help get started
L. Courtes — Software Documentation—That Thing We Love to Hate 26
![Page 27: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/27.jpg)
give examples to... illustrate concepts
L. Courtes — Software Documentation—That Thing We Love to Hate 27
![Page 28: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/28.jpg)
give examples to... illustrate functions
L. Courtes — Software Documentation—That Thing We Love to Hate 28
![Page 29: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/29.jpg)
reference doc calls for rigorous wording
L. Courtes — Software Documentation—That Thing We Love to Hate 29
![Page 30: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/30.jpg)
reference doc calls for rigorous wording
L. Courtes — Software Documentation—That Thing We Love to Hate 30
?
![Page 31: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/31.jpg)
reference doc calls for rigorous wording
L. Courtes — Software Documentation—That Thing We Love to Hate 31
![Page 32: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/32.jpg)
reference doc calls for rigorous wording
L. Courtes — Software Documentation—That Thing We Love to Hate 32
![Page 33: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/33.jpg)
form
L. Courtes — Software Documentation—That Thing We Love to Hate 33
![Page 34: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/34.jpg)
use consistent vocabulary & typographical conventions
L. Courtes — Software Documentation—That Thing We Love to Hate 34
![Page 35: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/35.jpg)
use consistent vocabulary & typographical conventions
L. Courtes — Software Documentation—That Thing We Love to Hate 35
![Page 36: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/36.jpg)
don’t be needlessly verbose
L. Courtes — Software Documentation—That Thing We Love to Hate 36
![Page 37: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/37.jpg)
don’t be needlessly verbose
L. Courtes — Software Documentation—That Thing We Love to Hate 37
![Page 38: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/38.jpg)
use (hyper)links to concepts, and indexes
L. Courtes — Software Documentation—That Thing We Love to Hate 38
![Page 39: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/39.jpg)
use (hyper)links to concepts, and indexes
L. Courtes — Software Documentation—That Thing We Love to Hate 39
![Page 40: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/40.jpg)
use (hyper)links to concepts, and indexes
L. Courtes — Software Documentation—That Thing We Love to Hate 40
![Page 41: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/41.jpg)
media
L. Courtes — Software Documentation—That Thing We Love to Hate 41
![Page 42: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/42.jpg)
media
L. Courtes — Software Documentation—That Thing We Love to Hate 42
![Page 43: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/43.jpg)
media
L. Courtes — Software Documentation—That Thing We Love to Hate 43
![Page 44: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/44.jpg)
media
L. Courtes — Software Documentation—That Thing We Love to Hate 44
;
![Page 45: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/45.jpg)
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
![Page 46: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/46.jpg)
LibreOffice, OpenOffice, & co.
L. Courtes — Software Documentation—That Thing We Love to Hate 46
![Page 47: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/47.jpg)
LibreOffice, OpenOffice, & co.
L. Courtes — Software Documentation—That Thing We Love to Hate 47
are you serious?!
![Page 48: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/48.jpg)
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
![Page 49: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/49.jpg)
Unix man pages
L. Courtes — Software Documentation—That Thing We Love to Hate 49
![Page 50: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/50.jpg)
Unix man pages
L. Courtes — Software Documentation—That Thing We Love to Hate 50
no structure
no indices
no hyperlinks
![Page 51: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/51.jpg)
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
![Page 52: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/52.jpg)
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
![Page 53: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/53.jpg)
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
![Page 54: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/54.jpg)
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!
![Page 55: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/55.jpg)
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!
![Page 56: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/56.jpg)
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
![Page 57: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/57.jpg)
LATEX, a false good ideahttp://www.latex-project.org/
L. Courtes — Software Documentation—That Thing We Love to Hate 57
![Page 58: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/58.jpg)
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.
![Page 59: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/59.jpg)
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.
![Page 60: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/60.jpg)
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
![Page 61: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/61.jpg)
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
![Page 62: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/62.jpg)
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!
![Page 63: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/63.jpg)
DocBookhttp://docbook.org/
L. Courtes — Software Documentation—That Thing We Love to Hate 63
![Page 64: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/64.jpg)
DocBookhttp://docbook.org/
L. Courtes — Software Documentation—That Thing We Love to Hate 64
![Page 65: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/65.jpg)
DocBookhttp://docbook.org/
L. Courtes — Software Documentation—That Thing We Love to Hate 65
medium-independent!
![Page 66: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/66.jpg)
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
![Page 67: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/67.jpg)
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
![Page 68: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/68.jpg)
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!
![Page 69: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/69.jpg)
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
![Page 70: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/70.jpg)
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
![Page 71: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/71.jpg)
GNU Texinfohttp://gnu.org/software/texinfo/
L. Courtes — Software Documentation—That Thing We Love to Hate 71
![Page 72: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/72.jpg)
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
![Page 73: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/73.jpg)
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
![Page 74: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/74.jpg)
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
![Page 75: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/75.jpg)
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
![Page 76: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/76.jpg)
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
![Page 77: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/77.jpg)
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
![Page 78: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/78.jpg)
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
![Page 79: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/79.jpg)
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
![Page 80: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/80.jpg)
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
![Page 81: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/81.jpg)
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
![Page 82: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/82.jpg)
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
![Page 83: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/83.jpg)
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
![Page 84: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/84.jpg)
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
![Page 86: Software Documentation That Thing We Love to Hatesed.bordeaux.inria.fr/seminars/documentation_20120619.pdf · 2020. 2. 18. · SOFTWARE DOCUMENTATION THAT THING WE LOVE TO HATE Ludovic](https://reader034.vdocuments.us/reader034/viewer/2022051915/6006426ec8fd7a0dbd406aff/html5/thumbnails/86.jpg)
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