Looking for Best Practices for Design Engineers

I have seen companies from both sides of this argument. The successful ones do the work once only. Those that fail seem to make the same mistakes over and over again.

Even though you are working for a government department there is no excuse for not doing the engineering properly. I would expect that you should already be operating ISO9001 processes. Get audited for that and you may find that some of the documentation issues get aired. In addition, some books you may find helpful:-

"The Art of Designing Embedded Systems" by Jack Ganssle. Newnes ISBN 0-7506-9869-1 (pay especial note to Chapter 2)

"Configuartion Management: The Changing Image" by Marion Kelly McGraw Hill ISBN 0-070707977-9

"Introduction to Systems Analysis" by Steve Skidmore and Brenda Wroe NCC Publications ISBN 0-890152-630-4

"Introduction to Systems Design" by Steve Skidmore and Brenda Wroe NCC Publications (ISBN not available).

"The Handbook of Walkthroughs, Inspections and Technical Reviews: Evaluating Programs, Projects, and Products" by Daniel P. freedman and Gerald M. Weinberg Dorset House ISBN 0--932633-19-6 (Third Edition)

"How to Design and Implement A Bad System" by Ronald B. Smith Petrocelli ISBN 0-89433-148-5

"Software Failure: management Failure" by Stephen Flowers Wiley ISBN 0-471-95113-7

The theme that runs throughout all the above is that you need documentation to assist in protecting your IP, backing up the fallable memory of the engineering and management staff and to provide an audit trail to prove (unequivocably) that you have achieved what you stated you would achieve.

In other words, there are often financial reasons that mandate a well-documented engineering design process. However, not all engineering environments have strong motivation for a well-documented design process.

If you can show your coworkers why more formal documentation would save them money and time down the road, they will be a lot more eager to try that approach. If the only motivation you can offer is "other people do it this way" then you're going to have a harder time getting people to change how they operate.

In short, documentation is a means to an end, not an end in itself. Add as much as you need to meet your goals.

Kelly

Very well said. As in all things to do with engineering, it's a matter of finding the right balance.

Dan

I expect that the manager in your design section cares about speedy completion of projects much more than the quality of the documention.

From observing the careers of myself and other engineers, I think that zero documentation is actually good practice for sucessful engineers in terms of making oneself indespensible. Besides, if the boss dosen't care about documentation, your are better off to use your time more effectively by moving on the the next project.

My advice is to look after your own work, and not worry about issues that should really be the concern of management.

regards, Johnny.

The older I get, or maybe the more experienced ;o), the more I find I need. Five years later, there's never enough.

Alf.

A simple way to get started is to encourage them all to use day books. This is just a A4/Legal exercise book that they use everyday. In it they should do all their design calculations and describe their design decisions. Tell them it will benefit them greatly down the line when:

1. Someone wants to do a modification/enhancement and they need to be sure the design will still work.
2. When there are production problems and they blame the design (as they always do).

This applies to all engineering disciplines.

IAn

I find that most things I write on paper has a tendancy to dissapear. (Under piles of other paper mostly). I prefer to have these sort of notes in electronic form. Do anyone know of an application that can be used as an electronic "Day Book".

Regards Anton Erasmus

Real Enginers and their logbooks are very seldom separated. I have a pile of logbooks going back several years (as well as old files etc). It is nice to look back at them once in a while. The logbook can get you out of a lot of hot water when those awkward questions do arise.

Things to note:-

• Rapid Reference phone/contact list for when you need it in an emergency.

• Important Decisions by you and others that affect the work you are doing.

• Test Results (before you enter the results into a spreadsheet for presentation).

• Sketches, Rough Schematics, As-Built notes (when the assembly guy didn't follow your carefully prepared instructions)

• To-do lists (to keep you focused on what to do next)

• Base-line data (connector layouts, indicator meanings, common error codes, proven workable sequences, default settings etc).

I am sure you may think of other things to record as well.

I think you are looking at this the wrong way. There are considerable benefits to being what you are calling a "bad" engineer:

• You finish faster if you don't document your code.

• You get "somewhat working" code up and impressing executives with demos faster. Then, you can relax and soak up that paycheck with those months upon months of "small fixes" to the product, during which you will be rewarded for your outstanding bug fix rate.

• Your job is secure. Nobody can understand your code.

• By the time anyone in management realizes that the code is FUBAR, you will be gone to another company, with star status and higher salary, or you will be in the management of your current company, and can blame in on your employees. Its win-win.

• More than half of products don't make it to market anyways. Why waste time on something that is never going to ship ?

• Most "first approaches" are wrong in any case. The code will have to be rewritten, so why spend a lot of time on it.

• Managers don't read code, so less documenting means more time to suck up to the boss.

And on and on. The co-workers who you put down for not documenting are smart. You will become more and more angry as you watch them rewarded for their successes and promoted to be your manager, at which time they can have you fired for your bad, continuously complaining attitude.

"There is no shame in mediocracy... I am the patron saint of mediocracy!" [From "Almadeus"]

Not necessarily good advice.

If you have information or advice that would help management reach a decision impacting your own work, it is best to pass it along. If you don't pass the information along and a decision is reached that you don't like, you have no one to blame but yourself.

Setting up a Wiki isn't too difficult, and it's easier than doing everything in raw HTML.

I was relatively skeptical when we set up a departmental Wiki at work, but within a month there was enough content there to make the thing useful. It's been almost a year now, and it's now the hub for all of our engineering documentation.

Kelly

I suppose you have a manager that like to get advice from graduate engieneers.

regards, Johnny.

A simple rules in this business is that you only touch what brings you the laurels. So if none acknowledges documentation, don't do it. If none acknowledges optimal code, don't do it. And so on. Why should you behave different to your CEO which only optimizes the quarterly results ?

Rene

They don't have to like it.

How are managers to know how they are doing if they never get any feedback from those they are managing?

I'd strongly discourage this digital stuff:

1. Proprietary data formats have a short lifespan. You won't be able to read 2005's logbook with the software available in 2025.
2. Physically written data has a solid non-ephemeral aspect which is a great reassurance if you're digging your way out of a hole (legally speaking). Of course, if your original data don't support the circuit you released, then maybe you don't want to be able to check your work... :)
3. It is an immense amount of effort to draw schematic fragments, neat tables, calculus symbols etc. if done electronically. Ten minutes' work with a pencil is an hour's work with word processor, spreadsheet, equation editor, CAD software, etc. This is five times more true if you are experimenting on paper (i.e. messing about with alternative connection methods, component values, whatever). Sketch it by hand. Draft it into a schematic later.

Don't use loose pages. Use a strong logbook. They sell these books specifically for such purposes. This book is chunky and hard to lose. Small scraps of paper (tables from datasheets, plotter outputs, etc) can be glued into the logbook.

Excepty when the code MUST pass certification for the application it is being incorporated into. Then, lack of documentation is going to cost you plenty of sleepless nights while you try and figure out why certain curious things keep happening unexpectedly; especially if the customer witholds payment until the whole deal is right.

Only if they haven't closed off your escape route first.

So you work for companies that waste your and their time on useless stuff from the get go. The saner ones do some elementary market research and product requirements determination before they start down the design and build road.

So why write code before you understand the requirements? Do the work in the right order and you spend less time re-writing. You should, after a while, get better than 80% right first time (so only 20% might be in for the second run).

Sucking up is something I never have to do. I am currently working as an integral part of a larger team and feel I am well respected by my colleagures and the upper management (to the point I even lunch with the CEO on occassion).

I get the feeling that a smiley or two was missed out somewhere along the way.

I agree with you that currently there is nothing that comes close to the flexibility of paper. The problem comes in because it has a tendancy to accumulate.

If you search for the term "non-realistic rendering", you should find quite a few research projects where they are trying to develop CAD systems with which one can sketch as easily as on paper, but which then can be converted into true electronic information automatically.

The "non-realistic rendering" comes in where one wants to take a full

I think over time, with PDAs and this sort of software one would be able to get the flexibility and ease of use of paper, together with the powerfull sorting and searching facilities possible with electronic systems.

I was hoping somebody knew of an available application which is on it's way towards this goal.

What I am currently doing is to use paper during a project. (A file with the ability to add loose papers etc). When a defined phase of the project is complete, I scan in the papers in PDF format. I then generate an "electronic" version of the paper, which can be put onto a server, where it is easier to find when wants to check something.

I would be interested to hear abouts other peoples efforts in combining paper and electronic formats.

Regards Anton Erasmus

There is a very good reason why a comic strip like Dilbert exists and why it is so popular with technical people. Most companies have some aspects with the Dilbert world - otherwise people would not relate. As in everything one gets cases on the extrem ends. If one ends up at a company where the company is at the Dilbert end of the extreme, then the only way to survive in such a company is to follow the previous posters advice. It takes a long time, and dedication to build up an organisation where things are done as they should be. It is amazing how fast such an organisation can end up at the Dilbert end of the spectrum when one of the top level managers is a bad apple.

Regards Anton Erasmus

How much is your manager going to like you if you had information he should have known but didn't think to pass it on?

Rufus

(biting his tongue about the political analogies to this statement)