Design Documentation - Page 1
Forum section: electronics / general

author: Pack34
author_rank: Frequent Contributor
timestamp: April 26, 2013, 01:32:47 am
content: Is there some sort of best practice for design documentation? For example, a high abstraction circuit overview followed up with sub circuit explanations on what the circuit is doing and why certain components were chosen and my math showing the calculated values. Do you type up your design notes and scan in your math? Type everything up? Include explanations and math in schematics? Some sort of formal report? I feel that I could document my work better and was wondering what I should strive for.Any thoughts?

author: c4757p
author_rank: Super Contributor
timestamp: April 26, 2013, 01:50:04 am
content: Quote from: Pack34 on April 26, 2013, 01:32:47 amWell, I can't comment on the main question, but as a former math student I have to address this. Please become familiar with a good equation entry system and use it. Nobody wants to see your nasty handwriting.

author: krish2487
author_rank: Frequent Contributor
timestamp: April 26, 2013, 02:33:23 am
content: HP documentation ... have a look at any of their older service / user manuals.. it will give an idea as to how to plan and approach documentation.. power supply, function generator, counter, multimeter.Sent from my Chaser using Tapatalk 2

author: KJDS
author_rank: Super Contributor
timestamp: April 26, 2013, 11:35:25 am
content: If you want best practise, or at least an example of just how much documentation it is possible to generate, work on a military satellite project.For each board the doc set will contain:-A design description documentA Parts list, including qualification levels required for all components and batch control information for every componentAn assembly methodA derating analysis, showing the rating and dissipated power, max voltage and current for every component, the junction temperature of every semiconductorA MTBF calculationA FMECAA set of analysesA worst case analysisAn end of life analysis, showing how the degradation of Hfe etc due to radiation will affect performanceA test methodA qualification methodThe test resultsThe qualification resultsand I suspect, as it's been a few years since I've worked on a milsat job that I've missed some, and also, as it's been a few years since I've worked on a milsat project my fingers are now worn out from typing that list.

author: free_electron
author_rank: Super Contributor
timestamp: April 26, 2013, 02:22:02 pm
content: Math ? Sod the math !Schematic, pcb layers , design notes ( like why a specific part needs to be a foilcap , or why this expensive opamp and not some other )Math is irrelevant (unless there is some non-linear compensation equation . You may want to note that)But all the simple stuff can be recalculated quickly. We really son't need to see how you calculated the series resistor for every led...A blockdiagram is handy as well . Here we have an oscillator, a filter, two mixers , an input amp , a rectifier , the a/d converter with its reference .. Blablabla. The oscillator needs a tin can. The crystal of the cpu needs to be shielded. The opamp is a low input bias tpye , and we need a guard ring around the mixer input stages. Diodes in the rectifier need to be ultralinear blabla..But, if schematics are well drawn they will already be partitioned and properly labeled. Layout and special parts info will be noted on the schematics.There will also be an assembly manual with tips and tricksAnd there will be a complete BOM including part manufacturer, EXACT partnumber, vendor and order code and possible substitutions.Specifying a 10uf 16v is like saying 'a chicken'. What weight ? Cornish hen , plain white, old egglayer , ? With the head ? Want the guts too. .does it need to be dead ? Etc ....

author: Pack34
author_rank: Frequent Contributor
timestamp: April 27, 2013, 05:02:53 pm
content: Excellent advice! I've been able to find some snippets of some HP documentation and it's definitely something to strive towards.I've had my hand in some MIL spec design documentation and I've found that it provides such a large quantity of detailed information that the law of diminishing returns kicks in and it seems to tell you less about what's going on. I guess what I'm looking to achieve would be a basic, but thorough, board level design doc.Just in case someone finds this post while trying to put together something similar, I've included the initial layout that I'll be experimenting with.- Errata- Revision notes and history- Design purpose and overview- - Basic description of what the design is for, where it came from, and why- - Block diagram showing function- - Highlighted DXF of sub-circuits- Sub-circuit detail- - This section would pull heavily from the schematics with detailed descriptions of what's going on in the circuit, why, and what components were chosen and why.Would it be wise to include complete and unedited copies of the schematics and BOMs at the end of the design doc, or keep them completely separate? I can see the value in having a single source of information for a design but this would cause issues due to duplicated information. It's easy to remember to update the BOM after a component change but having to make that one change in multiple locations, human mistakes happen. Perhaps, if I could have the doc dynamically pull data from the BOM spreadsheets and exported PDFs of the schematics. Could work, but it might make the whole thing more complicated than I'm hoping.

author: krish2487
author_rank: Frequent Contributor
timestamp: April 27, 2013, 08:55:27 pm
content: Just my 0.02$.Include the schematics in the design doc.Keep the detailed BOM with ref des and the schematics and the manufacturers etc in the service manual(if you are planning for one)It gives a more consistent approach to the documentation, but also is more tedious to work with as you noted.Also just keep the schematic to a single sheet as I find it is more easier to understand rather than split across multiple pages.Also when you are drafting the schematic make sure the general layout and specific sections in the actual circuit are highlighted and consistent across the documents..I am not claiming to be proficient with documentation ( I too am trying to become better at my own documentation)....But the more you implement projects, the more insight you ll have into managing different parts of production/assembly/service and traceability for a product.Heres my take on a project I have done earlier .. A simple 3 phase waveform generatorThis is just how I like to organise and divide sections of circuits.In the end it is just how you would like to do the job.

author: Neilm
author_rank: Super Contributor
timestamp: April 27, 2013, 10:19:26 pm
content: Quote from: krish2487 on April 27, 2013, 08:55:27 pmI very disagree with this. I have seen boards that tried to fit everything onto one page - it was a complete nightmare to follow. There was so much circuity that the designer had increased the page size to A0 and it was crammed.Having said that - I would always try to split a design up into logical blocks - Power Supply, micro, signal conditioning etc. I would then try to dedicate a page to each and put all the circuitry for that function on the page. I would also try to use a hierarchical layout. First page would basically be a block diagram of the board. I find this helps show the relationships between the various blocks, allows me to fully understand the signal paths and then becomes an aid to laying out the board. (i.e these bits of circuit are related so must be near each other on the board.) Descending the blocks then shows the next parts, possibly with more blocks below.As I typed the above, I realised that is the same approach I have to coding...Neil

author: krish2487
author_rank: Frequent Contributor
timestamp: April 28, 2013, 05:04:28 am
content: As i said...it is largely subjective....Splitting a schematic into multiple pages is purely upto the individual..I want a schematic laid onto a single page as I can clearly understand where each net is going to and coming from...Then again.. it is an individuals choice.. and the company policy...I am not averse to the idea of having schematice spread across multiple pages.. just that it becomes cumbersome toread and understand the schematics..having said that...it is really not difficult to do so either...

author: KJDS
author_rank: Super Contributor
timestamp: April 28, 2013, 09:56:18 am
content: I've worked at places that didn't have anything bigger than an A3 printer. One schematic ran to 26 pages but it was well enough orgainzed for it not to be an issue.As far as best practice of documentation goes, it depends on who is likely to be using the docs for what.For commercial stuff, repairs may be done all over the world, so a decent repair manual is high on the list of what needs to be good. The repair manual for a satellite is usually bottom of the list of required documents.When I had responsibility for deciding what documentation was generated on a project, the document I was always most insistent that was up to date for each design gate was the financial justification. I've found that a project being pushed through without financial reward will always end up a mess in many ways.