Best Practices for Documentation During Development Process?

[beaker353]

At any one time I will be working on a handful of various electronics related work or personal projects.  My work stuff is more along the lines of one-of custom industrial control applications and my personal projects are open source hardware projects for the hobbyist types.  6 months ago at work I was asked to back-burner a micro controller project I was about 90% done with and help some other co-workers move forward a different project that deemed more important by management.  Late last week I was finally able to get back to my micro controller project and found myself in a problem that I’m pretty sure is common among engineers. 

When I opened my code and schematics I felt like I didn’t know what I was looking at and had to spend the entire day reverse engineering my own work just to get back to where I was before I had to pause the project.  I can now see I’ve relied too heavily on the grey matter between my ears to keep all my notes of my development process; where I am in the design process, what bugs there are to squash, and where I still need to investigate further.  I feel I have a pretty good system for keeping track of research and version control of my code/schematics/layouts.  I have a folder for each project with various subfolders like datasheets, app notes, physical drawings, and general research.  I never over-right a version of my code/schematics/layouts and always start the day (or major functional step) with a new revision number leaving previous versions as-is.

I’m looking for a better system for keeping track and organizing of the million little notes that pop through your head during a typical development cycle.  For example, I’ve take a measurement to check something inconsequential at the time to later find out down the road that that measurement would really save me critical time now.  Or a note that you need to source a different part that has a lower physical clearance before the next PCB spin.  Post-it notes and legal pads don’t seem to be cutting it anymore.

What are some of the systems that you guys, and gals, use for development process documentation?  I would really like to form some good habits now before my projects get bigger and more complicated to keep hold of.  And yes, I am asking for the more life-experienced engineers to chime in here in particular... Thanks!

-EM

[Paul Price]

Try getting rid of all that old-fashioned way of keeping notes.

Try using a computer.

That's why they invented scanners on top of printers and databases on top of desktops.

[andyturk]

Try getting rid of all that old-fashioned way of keeping notes.

Try using a computer.

That's why they invented scanners on top of printers and databases on top of desktops.

[andyturk]

...  Post-it notes and legal pads don’t seem to be cutting it anymore.

I know the feeling. Can't help with "best practices", but ...

The thing that's saved me a couple of times is having one (physical) notebook where I write those little notes down. Knowing *when* I did some work means I can usually flip back to that point in time and find where I wrote down measurements, circuit diagrams, etc in the notebook. The problem with post-it notes (for me anyway) is there's no standard place to go looking for them. But the notebook is always there. Losing it would really hurt, but fortunately, that hasn't happened yet (knock on wood).

I also use Evernote (www.evernote.com) for keeping track of web-oriented stuff and billable hours. If it's in Evernote, I can find it. If it's in the paper notebook, I can find it. But post-it notes and unbound pages have a half-life measured in days on my desk.

[codeboy2k]

I take some notes during a projects development.. I hate to backtrack over stuff I've already done. I don't note every measurement I do. I try to decide if it's worth noting or not.

I just use a file in the dev tree usually, I don't have any software except for when I need to macro-manage the defined deliverables and the tasks and resources needed

I once worked with a guy that must have been borderline OCD or something... he had on his desk a horizontal row of lined notebooks of his entire work-life, every page dated, every entry time logged, everything he did , day after day, was logged. He could even tell you what was said at an informal standup hallway meeting that took place at any time in the past.

At both formal and informal meetings, he was constantly flipping through his notebooks to find a needed piece of information that everyone else was struggling to remember.. he had already wrote it down weeks, months or years before, at the time it was said or done.  whatever he was present for, got written down in his book, even if he didn't do it... if he saw it or heard it, he wrote it down

We found ourselves going to him when we needed something too

[David_AVD]

I once worked with a guy that must have been borderline OCD or something... he had on his desk a horizontal row of lined notebooks of his entire work-life, every page dated, every entry time logged, everything he did , day after day, was logged. He could even tell you what was said at an informal standup hallway meeting that took place at any time in the past.

That's not borderline OCD, that's pretty full-on !   

[Hypernova]

I take some notes during a projects development.. I hate to backtrack over stuff I've already done. I don't note every measurement I do. I try to decide if it's worth noting or not.

I just use a file in the dev tree usually, I don't have any software except for when I need to macro-manage the defined deliverables and the tasks and resources needed

I once worked with a guy that must have been borderline OCD or something... he had on his desk a horizontal row of lined notebooks of his entire work-life, every page dated, every entry time logged, everything he did , day after day, was logged. He could even tell you what was said at an informal standup hallway meeting that took place at any time in the past.

At both formal and informal meetings, he was constantly flipping through his notebooks to find a needed piece of information that everyone else was struggling to remember.. he had already wrote it down weeks, months or years before, at the time it was said or done.  whatever he was present for, got written down in his book, even if he didn't do it... if he saw it or heard it, he wrote it down

We found ourselves going to him when we needed something too

I would hope he doesn't hold grudges as well as he hold notes...

[nctnico]

I usually draft up some spec sheet which outlines the goals and requirements. Subject to change ofcourse but its a good starting point. I usually keep all the notes, component information, etc in a binder. I do this for both hobby projects and paid projects.

[KJDS]

One binder per projects, whether it's ring, spiral bound or whatever doesn't really matter, even a section of filing cabinet will do, so long as it's got the requirements, up to date notes on the project, meeting minutes, clarifications of customer requirements etc and explanations for design decisions. A design description, bug list, test results and so on.

There's no reason that this file can't be electronically stored so long as the back up process actually works.

[Smokey]

+1 to plain old paper lab notebooks for recording test data at the bench.  That's only part of a good system though.  You need some consistent way to document things like ECO so you can know what changed from one version to another, and some way to keep track of finished requirements and things which still need to be completed, but that's the easy part as far as I'm concerned.  That's just keeping spreadsheets and being consistent.

The hard part for me is keeping all the day to day development data from different places organized and remembering where it is in case I need it later.  I may collect some automated data in a spreadsheet, write some notes in the lab notebook, take some screen shots and scope plots, and maybe write some code.  I keep all digital stuff in version control, and the lab notebook has a table of contents and page numbers.

One thing that I use to keep all that organized is writing a daily summary report to someone.  There is usually someone that requested it or just wants to keep updated on what I'm doing, but I'll usually do it in my version control comment even if no one asked.  It's a great place to keep all the important info together with notes about where to find the relevant files/notes in version control and the lab notebook.  Plus it gives you some time to go over what went wrong and what went right in relation to the big picture of whatever you are working on.  A bunch of times the data didn't make sense when I was recording it, but when I was writing a quick report about it everything clicked.  It doesn't have to be super long, just the important facts.  Something searchable and chronological is best like email or version control commit notes.  I've found its pretty easy to go back now and see what I was doing at any given time and where the relevant data is. 

Just be careful since it's really obvious when you spent the whole day napping or reading EEVBLOG since the report will be thin on content  

That's the work system at least.  At home I just keep a personal version control server and try to write good commit notes about whatever I was working on.  That's usually good enough for the small stuff.

[ftransform]

I use poorly written out post it notes that end up getting lost 2 days after they are written and re invent the wheel constantly 

[David_AVD]

The advent of the digital camera and cheap HDD storage has been a great thing.  We take pictures (overall and details) of almost everything we build now.  Very handy when we need to build another one of those "we'll never need to make that again" items!  The photos go onto the network in a project folder along with various other info.

[westfw]

Well, I try to add notes to the computer files where they belong.  For example, if I have my act together a PCB layout file will have a layer for "Edit History", and another for "to Do", and will get a bunch of notes in other layers that might otherwise have ended up on scraps of paper.

[beaker353]

Sounds like a spiral bound notebook for my work bench on one for home bench sounds like the way to go. Low tech just beats out high tech sometimes. Found an interesting guide on lab notebooks that MIT made for its mechanical engineering department. http://web.mit.edu/me-ugoffice/communication/labnotebooks.pdf.  I remember my aunt, a maternity nurse, saying once that if it happened in her ward, it was logged down. Not that it would have that important of bearing for my situation , but does this guide represent what a more professional/established institution would ask of its engineers? I highly doubt I would every ascend to that level in the industry, but it would be nice to at least have some of the same habits.

- EM