Re: literate programming, development log -- ideas? (ominbus reply)

[Tim Cross]

Greg Minshall <minshall@umich.edu> writes:

> Tim,
>
> thanks for your comments.
>
>> A lot depends on whether what you want is an org file which documents
>> the current state of play or one which is more similar to a lab book
>> which contains a more chronological type evolution of ideas and
>> experiments. I often setup completely separate org 'projects' which will
>> consist of multiple org files and will move things between different
>> files as the project evolves. In some extreme cases, I may even have
>> multiple git branches and will often use git tags to mark specific
>> 'milestones'.
>>
>> How I decide whether to use a date tree with notes, branches, tags,
>> archive sections/files, separate org files etc is typically determined
>> by how likely I might be to want to review or go back through previous
>> work/experiments/decisions. Working this out can take a bit of time and
>> experimentation, but in general, I rarely need to checkout old versions
>> or even open archive trees/files. I do have a journal file for each
>> major project which has lots of ideas, random thoughts and even small
>> experiments (with source blokcs) and I tend ot have a large 'reference'
>> file which contains notes and links to external references and then a
>> 'main' org file, which reflects the current state. 
>
> my current curiosity is in how to integrate lab book, brain storming,
> functionality into my projects.  it seems as if, in an extreme case, you
> might possibly have
> - a lab book sort of file (i.e., date order, minimal "going back and
>   correcting entries")
> - a journal file, unstructured, not-infrequently updated, notes, URLs,
>   etc.
> - the "main" org file -- that which "ships".
> - an archive file (one per each of the other?)
>
> for any given project, is the evolution from =foo.org= to this larger
> number sort of organic, in the sense that you start with one file, then,
> at some point, say, "okay, i need to put these bits in a new journal
> file"?
>
> and, trying to leverage the brain cells of others, have you tended to
> settle on any sort of consistent naming scheme for the different files?
> =-log=, =-notes=, etc.?
>
> i suspect that if my brain were more git-shaped, i'd find the idea of
> separate files easier.  i.e., my instinct is to think of each of these
> files as having a version-path independent of the others.  rather than
> the git-view, which is that the version-path is the commit-path, and
> each commit includes the (mostly-temporally) related versions of each of
> again, thanks!  Greg


For me, the growth was quite organic. I still have quite a few single
file 'projects' where everything is in one file (with top level headings
for the different 'bits').

In fact, nearly all my org usage has followed an organic approach. When
I first started with org, I made the common mistake of getting in and
defining lots of todo states, tags, templates for different structures,
lots of capture templates etc etc. I later realised this was a big
mistake and ended up being a fine example of over engineering.

I ended up going back to a stock standard org setup with next to no
configuration. I then used this 'out of the box' setup for a while and
worked out how to do what I wanted using what org already had. I avoided
installing any additional org related packages. Once I was familiar with
what org has and how to use it, I then began to refine my workflow bit
by bit. I slowly started tweaking my configuration and added some simple
elisp functions to make my life easier. I then systematically looked at
various org packages I had heard about and installed a couple which I
found useful.

I now have a very workable and nice workflow where org is integrated
into most of what I do. There is a bit in my config, but most of it is
just setting various org variables, a few capture templates, a custom
agenda view and some tweaking to some of the export stuff. While I use
org pretty much daily, there is a lot of org I just don't use. For
example, I only use tags very sparingly. I use babel to generate my
init.el, numerous config files (my zsh shell setup, my mbsync and lots
of other config files) and I have some language 'logbook' projects where
I experiment and learn different languages, frameworks etc. I tend not
to use babel/literate programming with full on coding projects. I will
use org for documentation, issue tracking, notes etc. However, for
'real' code projects, I tend to keep the code in 'normal' language
dependent files rather than adopt a full literate/noweb style of
development. I do often use org to document and manage deployment
scripts and some 'devops' type stuff though. 
-- 
Tim Cross