26/04/2011

Documentation

Within my work, as with many (most?) other professions, I have considerable need to produce documents. For me these usually take the form of:

  1. Ongoing notes - for my own use and occasionally for discussion with my supervisors
  2. Communication - invariably via email
  3. Recording results - as they are produced from experiments
  4. Reporting on progress - monthly/yearly formal reports
  5. Papers - Eventually for publication in journals or similar
  6. Thesis - Finally for submission for my PhD
Years ago my only option would be to handwrite all of these, but thankfully times have changed. This is particularly fortunate for me (or perhaps it is because of this), as my handwriting is appalling. So, although I still keep a handwritten log book for immediate scribbling, I am making an effort to digitise my notes as far as possible.
As I've mentioned before, I'm very much a believer in using the right tool for the job; to this end I thought I would note down what I'm using and try to justify my choices.

Plain text - I'm trying to use for emails, this can get difficult if I need to include equations or images, in these cases I will generally try to include them as an attachment.

Open Office Writer - I'm using to produce short reports. I have chosen not to use Latex (see below) for these as I am producing them as quick, short documents for dissemination to my supervisors; hence I find the WYSIWYG interface easier than going through Latex. I have considered setting up a Latex template but I don't think the extra hassle will be worth it in the end.
These documents I export to pdf format prior to dissemination (see a forthcoming post for reasoning). I also maintain these documents within my version control system (again see a forthcoming separate post).

Handwritten Notes - I keep a log book for scribbling down results and doing rough sketches, however I'm trying to digitise the important points from these as soon as possible as I can never find the page I wanted (no search facility!), or when I do find it that I can't read my own writing (yes it is that bad!).

Latex - (pronounced "lay-tec") I'm trying to use for most other work. My main reasons for use being:

  • The source is stored as plain text - this means it can be easily version controlled and differenced. (see a forthcoming separate post on this...).
  • It can compile directly to pdf with lots of nice extras included (menu's, interactive contents, hyperlinks, etc).
  • It separates the content from the formatting - allowing me to concentrate on one or the other, rather than worrying about items jumping between pages or links not working.
  • It is very flexible and can produce beautiful documents (especially where equations or complex formatting is involved).
I'll probably be posting more on Latex, as I have played with it to produce some interesting documents in the past. 

Do you think the way I'm doing things is sensible? Any questions, comments or arguments then please add them below!

No comments:

Post a Comment