Handling paper documentation

Question

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 :)

Answer 1

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

Answer 2

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.

Answer 3

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.

Answer 4

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.

Answer 5

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.