User Documentation and code snippets

Unit tests form part of the documentation for your code. They should probably not be the entirety of the documentation. In this learning hour we look at using code snippets in documentation.

Learning Goals

Session Outline

Connect: Documentation attitudes

Put a mark by the statements you agree with:

Concept - Tutorials and How-to documentation in practice

In the repo Recently-Used-List-Docs there is an example project with user documentation. It is a solution to the RecentlyUsedList kata in C++. The documentation uses Markdown Snippets and Jekyll. The idea is to write documentation in markdown that can be rendered as html. In the markdown we can include snippets of the unit test code.

Show how it works. Modify one of the snippets and some of the markdown and show the process to update the documentation. Relate this learning hour to the one on the Divio Documentation system for why the documentation is organized as it is.


In the Recently-Used-List-Docs project the how-to page is largely empty, with only some headings. The exercise is to fill in these blanks and then to add more documentation as you see fit. If you have time, implement a the new feature and write the associated documentation. Feature description:

The RecentlyUsedList class should not only reject empty strings, but also any strings on a blocklist. The blocklist is a list of strings that is provided on construction and by default is empty. The blocklist can be updated at any time by users of the RecentlyUsedList. When that happens any items held in the RecentlyUsedList that are on the updated blocklist should be removed. All the other items should be preserved in the original order.


If you’ve been working in small groups or pairs, compare the documentation each group has come up with. Discuss these question: