Embedded Documentation Deliverables

[Muffins]

Hi Guys.

I'm in need of a little help regarding my professional development and the value I can bring for the company I work for.

I work for a small company and I find myself in a position where I can grow into an embedded designer role. I am finishing up studies in electrical engineering and have a background in design. I am competent with CAD and currently working on industrial machines. I am the only EE guy there and don't have a mentor.

For my last two projects I have successfully created and programmed circuits that control the machines, I even designed the pcbs. They are simple 8bit projects but I managed to become independent the arduino environment and am becoming familiar with AVR and atmel studio.

My question now is, how do I become more professional? I have created these proof of concept solutions with very little documentation and planning and I am not sure what documentation I need to generate. Especially regarding the coding. I see myself on the software side of embedded but I'm a far ways from that. Perhaps we could choose an example project and I could give you guys the docs for feedback? 

[ajb]

It really depends on the project, but some very rough guidelines:   

Software should be mostly self-documenting at the source file level: IOW, the functionality of a given bit of source code should be apparent to anyone reading it.  Well-written, maintainable software eschews 'cleverness' and terseness in favor of readability and descriptive names.  Large projects will benefit from an architectural overview of how different modules interact, which modules are responsible for which functions, etc.  If you have complicated state transitions or information flows, then you may want to include suitable diagrams for those (if you made any diagrams or sketches in the course of writing the software, great, save those and include them in the documentation).  If you use any magic numbers or lookup tables in your software or have reduced complicated math to simpler application-specific algorithms or formulas then definitely document those and their derivations so that they can be recreated or adjusted in the future.  This may be done in a comment or in an external document depending on the complexity of explanation required.  Be sure to direct anyone reading the source code to external documents where necessary.   If you've written a library that will get re-used, then it's important to document the API.  The documentation for a library should be sufficient that it may be used successfully without having to read its source files.  As with most software, this starts with the library itself being well-written and having a sane and consistent API.

Hardware should have its main functional characteristics clearly documented: A diagram of the board or module with connection points labeled, voltage/current limits for all inputs and outputs should be clearly indicated.  Think about if you were handed the gizmo, what info would you need to make sure you hooked it up properly.  Be sure to document design values and limits, you don't want to have to go back and reverse engineer the whole thing because, say, someone wants to use it with an 18V supply instead of a 12V supply--you should already know whether or not that will work from the original engineering you did when you designed it.  At the design level, as in software, the source documents (schematics) should be largely self-evident in their function.  That means they need to be arranged in a clear and easy-to-follow manner.  Large projects should have block diagrams--if your project is organized hierarchically, you get block diagrams for free, but be sure to clearly label functional areas where applicable.  Make sure you document any engineering you do, like calculating component values or operating limits.  If you have 0.1% resistors in one particular part of the schematic, make a note as to why.  If you include a filter with a particular cutoff frequency, make a note as to why you chose that frequency.