views:

114

answers:

5

After every new program written a lot of paper documentation remains.

Apart from the usual scribble notes from the programmers there usually is a nice heap of papers containing physical model explanations, calculations and so on (equations, tables, graphs, little pictures describing variables ...)

We usually do numerically intensive calculations in console applications, which are not released to the public (remain in the house, only results go out). Before each project is finished all those papers have to be packed somehow with the application, so that one day, when someone will be reusing parts of it, has some idea what is what in there. So far, we've been using the 'dirty' solution of just scanning all of it, and packing it up on the disc with the application.

So I was wondering ... for all science guys here in a similar situation ... how do you handle project documentation which is needed, but not released to the public ? (the one that does, goes to the dtp laddies, and they make it nice and shiny - not our problem anymore :)

A: 

Here is some of the thoughts... Not so practical though :)

  1. We can make it part of our Check-in notes. This may help the developers going to maintain the application.
  2. Update the requirement document/Low level design document with these items
renil
+2  A: 

In the projects I've worked on we have done a lot of physics calculations in our programs and consequently we have a lot of whiteboard sessions with equations we are working on.

We keep a wiki for each major project and after each whiteboard session we physically photograph the whiteboard with a digital camera and upload/organize it within the wiki. We also scan in paper documents from developers notebooks if it is important and include it in the wiki as well.

Then, we back up the wiki on disc for storage. So our solution is pretty similar to yours, other than we use the project wiki for organization.

Simucal
Actually, some guys use wikis in their projects, yes. My team uses plain old pdf, so we just cramp everything inside :) For now we're thinking or trying to OCR the text, so to separate it from graphs and pictures and equations (to have at least some searchability through it).
ldigas
+1  A: 

If it's important, it seems to me you should treat the internal documentation with the same care with which you treat the public docs.

Patrick McElhaney
Theoretically, yes. In practice it is very rarely so. "In theory there is no difference between theory and practice. In practice there is a big difference."
ldigas
If we treated all our documentation the same way, no work would be done at all. People would just be doing documentation.
ldigas
+1  A: 

I create UI paper prototypes when designing the UI of an application, which produces lots of A3-sized papers (in one project we had many desks covered with papers). When the design is ready or it needs to be mailed to somebody, I take pictures of it with a digital camera, so that I can produce a series of pictures showing how to perform some tasks on the UI, which serves as documentation of how the application is meant to work. This serves also as a backup, in case somebody steals/cleans away the original papers.

Esko Luontola
+2  A: 

I use one of three options:

  • Keep everything in my lab notebooks, which I archive myself, for low-level stuff
  • Scan the paper document, and add to source control in pdf. It's ugly, but if someone needs it, it's there
  • Transcribe the equations, results, etc... in a clean format (usually Latex) for future reference, and again, add to source control. Official paper copy gets signed (I work in a highly regulated domain) and filed in a binder.
Kena
For "more official" documents we use similar principle (big archive room), only people here prefer mathml. The notebooks are a problem to us.
ldigas
Why are notebooks a problem?
Kena
Well, they're one of the reasons for this question. Scanning them is ok, but then we get just a lot of pdf filled with pictures. Also, have you ever tried reading a quickly written handwritten text after 5 years time (and that person is not around, of course) :) ?
ldigas