UP | HOME

Actually writing a programming tutorial

On my previous post I was trying to decide how to write a tutorial, that showed the evolution of the code.

I wanted to be:

• as close as possible to literate programming
• to be abele to show changes in the code, the lines that I deletede and added
• and to be able to change it.

In the end the workflow that I setteld on was:

1. Use stg init (to use git commits a stack)
2. Do

1.1 Write a couple of lines in a file 1.2 Commit with a heading written in Markdown 1.3 stg refresh

1. while still have something to say
2. Reorder commits (or patches as they are called in stgit) until you have a logical order
3. Export the series of commits to markdown tutotiarl with git-tutorial.
4. Edit the exported markdown tutorial.
5. convert to html

The process was very slow, because of lack of familiarity wit the tools. But I did finish a pretty simple tutorial.

I'm not sure that the benefits outweight the costs.

but definitively, where not yet there.

I would want somethnig that generates a literate program, like org-mode tangle. BUT that is aware of changes in the code repository.

Because that gives times.