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!

21/04/2011

Tool List

6 months in I've already used quite a few different tools. I'll initially start a list here of what I'm using and then post about separate issues later on.


  • Jabref - Reference managing software
  • Sciplore - Mind mapping software
  • Latex (TeXworks) - Typesetting
  • Foxit - pdf reader
  • Open Office - General word processing and Spreadsheeting
  • Bazaar - Version contol
  • Matlab/Simulink - Data analysis and Simulation
  • Pdf conversion software
  • Planner - gantt chart tool
  • Gmail + Google calendar - Email and Calendar
  • Winmerge - document merging and differencing
  • zbar - split the windows menu bar between two desktops
  • Irfanview - image viewer
  • Ghostscript - document viewer for postscript
  • Google sketchup - 3D CAD software
If there are any specific requests for posts on any of these tools then let me know in the comments, otherwise I will post about them as and when I have something interesting to say.

Personal tool choices

As a user of lots of different software, and a great believer in using the right tool for a job, I am fairly picky about what I use. I have a few specific requirements:

  • Open source - wherever possible I like to use open source software, partly because it is usually free (as in beer!), but also because it often comes with a good user base and readily available support. I'm very much taken by the idea that if I require a particular upgrade of alteration I can either email the developers directly or even make the change myself!
  • Operating system independent - At home I use Ubuntu Linux as my primary OS. At University I'm (more or less) tied into Windows XP. On my sponsors laptop I'm very much locked into Windows 7 (and also very limited in terms of software choices - maybe I'll come back to that).
  • Compatible - open source stuff is usually very good at this almost by default, but where I'm not able to use open source I need to be able to export and import stuff between programs.
  • Portable - As mentioned above, I'm using a lot of different machines and networks, therefore I need to be able to easily move stuff around.
There's probably some other minor stuff as well about ease of use, etc, but you get the general idea.

Intro!

OK, so I've decided to document some of the software tools I'm using during my PhD in a blog. I'm planning to do so for a number of reasons:

  1. I get a lot from the internet community, if I have a question about literally anything then I'll invariably type it into Google and get almost always get an answer. I'd like to be able to give something back to that community, and if even one person finds something useful in what I've posted then that's got to be a good thing.
  2. I need to practice my writing and publishing on technical subjects. Hopefully this will provide an opportunity to do this, with the possibility of (hopefully) getting comments on the results and thereby refining my writing style.
  3. My PhD is industrially sponsored and therefore I need to be a little careful about what I post in the public domain. I will therefore be attempting to keep the subject of this blog specifically on the tools I'm using, rather than it being about my research - I hope that these two can be kept separate.
  4. Having worked in industry previously, I am aware of a number of different tools and techniques that are available; however I am far from expert on the subject and therefore this will very much be a learning process for me. Any comments or feedback that I can get as I proceed will no doubt be invaluable.
I'm starting this around 6 months into a 3.5 year course and I've no idea if I will make past even a few posts - apologies if not! Let's see how it goes...