It's sometimes difficult to know where to start, or how to begin when preparing talks and trainings, or researching vulnerabilities. This article describes my current workflow and set of tools that help me in that process. From up above the clouds down to the details.

Finding the flow

Mindmaps are great to work with when an idea hasn't fully matured yet: There's a bigger picture, but not yet a structure, a flow. The visual aspect of mindmaps helps with finding patterns, and usually a pattern arises while the mindmap matures (emergent design). It also allows you to quickly reshuffle blobs of text, moving everything around.

For mindmapping I use the open source, cross-platform tool, Freeplane [1]. It stores mindmaps in the open freemind file format [2], an XML format (yes, that's Freemind, which was forked into Freeplane).

Organization or presentation

When a structure emerges, I use either Org mode [3] or reStructuredText [4] to write down the notes in a more detailed format. Why two different formats ?

Both use the underlying plain-text format, and are well suited to keep notes in.

  • Org mode is excellent for maintaining TODO lists and planning projects. Its format allows you to add various data properties, like tags, custom attributes and even can be used for time registration. It's excellent for organizing data.
  • reStructuredText is excellent for presentation purposes. It allows seamless exporting to numerous file formats like HTML, PDF or ePub. It gives you a lot of flexibility with regards to presentation.

For example when preparing presentations I choose reStructuredText, and when doing research I use the Org mode format. For trainings I use reStructuredText to prepare handouts, but I use Org mode for my own trainer's notes.

Backward design

When a pattern has emerged, I use backward design to structure trainings:

  1. Identify the desired results, the objectives
  2. Determine how those results can be measured, for example with assessments or challenges.
  3. Plan the training and develop the instructions.

This is also the same way that I write articles or blog posts for example: First write the summary, the objective, and then the actual contents. It's like with test-driven development: The requirements first, then the tests, then the actual code.

Plan for the future

Regardless the tools, I use open file formats. This allows me and others to easily collaborate, to re-use previous work, and of course it provides freedom. Anyone can use any tool, as long as it supports those file formats.

Preferably everything should to be stored in open file formats, which allows re-use of existing materials.

  • Both Org mode as reStructuredText use the plain-text file format.
  • When using references to articles, papers or websites I store them in an external file as bibtex [5], a plain-text file format. Bibtex files can be used by a wide range of programs. Both Pelican and Sphinx use reStructuredText, and both allow referencing bibtex files (the reference (Raymond, 2003) for instance is generated from a bibtex file). Org mode also allows including external bibtex files.

As the Unix philosophy states (Raymond, 2003):

Write programs that do one thing and do it well. Write programs to work together. Write programs to handle text streams, because that is a universal interface.

Therefore either Org mode for organization, or reStructuredText for presentation.

Of course, as they both use the plain-text format, it's easy to convert between the two in a later stage....



Eric S. Raymond. The Art of UNIX Programming. Addison-Wesley Professional, sep 2003. 1 2


comments powered by Disqus