Sie haben zwei verschiedene Fragen gestellt: Was sollte ein Vertragsingenieur bereitstellen und was sollten Sie für die interne Dokumentation eines Projekts haben? Ich werde zuerst die erste Frage beantworten. Dies setzt voraus, dass Sie beauftragt wurden, etwas zu entwerfen und einige funktionierende Prototypen mit genügend Dokumentation zu liefern, damit das Unternehmen es von dort übernehmen kann.

1. Schema natürlich.

2. Board-Fab-Dateien. Dies ist das Zip-Archiv der Gerber-Dateien, Drill-Dateien und einer Readme-Datei, damit jedes Board-House weiß, welche Dateien welche sind und welche besonderen Anforderungen es gibt.

3. Assembly-Dateien. Dies schließt die Stückliste und alles andere ein, was ein Montagehaus wissen müsste, um blanke Bretter und das Kit zu nehmen und fertige Bretter herzustellen.

   Die Stückliste ist im Grunde eine Inhaltsliste für das Kit und Beispiele dafür, wo man etwas kaufen kann, das kein Jellybean-Teil ist. Zum Beispiel muss so etwas wie ein Mikrocontroller vollständige Herstellerteilenummern haben. Andere Teile haben möglicherweise nur eine generische Teilenummer und mindestens ein Beispiel für eine Lieferanten-Teilenummer, bei der sie gekauft werden können. Ein Beispiel könnte ein LM324A-Operationsverstärker im SOIC-14-Paket mit der Mouser-Teilenummer 863-LM324ADG sein. Wieder andere Teile, wie ein 10 kΩ 5% Widerstand im 0805-Gehäuse, sind Jellybean-Teile und es ist keine Hersteller- oder Lieferantennummer erforderlich. Das Unternehmen hat wahrscheinlich bereits eine bevorzugte Quelle für diese.

   Sie sollten auch eine Platinenzeichnung und einen Teilelokalisierungsindex hinzufügen. Die Tafelzeichnung hat den Bezeichner für jedes Teil, der sich von der Tafel unterscheidet, da nicht immer jeder Bezeichner auf den Siebdruck gesetzt werden kann. Der Teileindex gibt die Koordinaten aller Teile auf der Platine an. Die gleichen Koordinaten sollten auf der Tafelzeichnung stehen. Ich füge die schematischen Koordinaten auch dem Teilelokalisierungsindex hinzu. Hersteller kümmern sich nicht darum und erhalten den Schaltplan normalerweise sowieso nicht, aber dies fasst alles in einer Datei zusammen und hilft anderen Menschen bei der Suche nach einem Teil im Schaltplan. Es sollte eine separate Board-Zeichnung für den unteren Bereich vorhanden sein, wenn dort etwas installiert ist.

4. Quellcode mit Build-Skripten und allen proprietären Tools, die zum Erstellen benötigt werden. Nach der Installation Ihrer Softwareversion und der von Ihnen angegebenen Software von Drittanbietern sollte der Kunde in der Lage sein, ein einzelnes Skript oder einen Befehl auszuführen, um die gesamte Software und Firmware zu erstellen, die Sie für ihn erstellt haben.

   Natürlich sollte der Quellcode klare i> und aussagekräftige i> Kommentare enthalten, die die Art von Fragen beantworten, die jemand, der neu in der Firwmare ist, wissen möchte. Wenn die Hälfte aller Quellzeilen keine Kommentare sind, machen Sie etwas falsch. Selbst wenn ja, besteht die Möglichkeit, dass Sie immer noch etwas falsch machen, da die meisten Leute beschissene Kommentare schreiben. Beispielsweise ist ein Kommentar wie "Schaltflächenzähler" für die Deklaration der Variablen "bcount" nutzlos. Sie i> wissen, was Sie meinen, aber halten Sie inne und denken Sie über den Kontext nach, in dem jemand anderes den Code liest. Vielleicht ist "Knopf" im Kontext des Geräts offensichtlich, aber gegen was? Sicher nicht die Anzahl der Schaltflächen, wie der Kommentar impliziert. Wie oft wurde die Taste gedrückt? Seit wann? Zeit bis der neue Staat entlarvt und für offiziell erklärt wird? Welche Zeiteinheiten? Die Uhr tickt, bis die gedrückte Taste zu einem langen Druck statt zu einem kurzen Klick wird. Uhr tickt seit dem Drücken, um mit einem Schwellenwert verglichen zu werden, um langes oder kurzes Drücken zu bestimmen? Wir werden es nie erfahren.

5. Firmware-Dokumentationsdatei. Zumindest enthält dieser Abschnitt alle verschiedenen Versionen, die Erstellungsdaten und die Änderungen gegenüber der letzten Version. Ich habe mein Build-System automatisch eine neue Sequenznummer für jeden Build innerhalb einer Version erstellen. Wenn eine Version veröffentlicht wird, sind neue Builds für die nächste Version ab Sequenz 1 vorgesehen. Die Sequenznummer jedes veröffentlichten Builds ist in der Firmware-Dokumentdatei aufgeführt, damit jemand erkennen kann, ob ein bestimmter binärer oder geladener Code der offizielle Build davon ist Ausführung. Beispielsweise könnte Version 21 in der Firmware-Dokumentdatei als Sequenz 14 beschrieben werden. Wenn jemand auf Version 21, Sequenz 7, stößt, weiß er, dass es sich um eine technische Zwischenversion handelt, und es ist nicht abzusehen, was sie tatsächlich tut. Es ist am besten, solche Versionen niemals herauszulassen, aber es passiert manchmal, möglicherweise sogar versehentlich, wenn sie in einen Chip geladen werden.

   Wenn die Firmware ein Kommunikationsprotokoll zu einem Host-Computer oder etwas anderem implementiert, sollte das Protokoll hier beschrieben werden. Wenn es wirklich kompliziert ist, können Sie es in ein separates Protokolldokument einfügen.

6. Optionale Entwurfsdateien. Kunden möchten möglicherweise die Dateien für den Schaltplan und die Karte in der von Ihnen verwendeten ECAD-Software. Normalerweise tun sie das nicht, aber wenn sie nach ihnen fragen, sollten sie sie bekommen. Versuchen Sie nicht, den Kunden daran zu hindern, Sie in Zukunft für Änderungen verwenden zu müssen. Das ist in erster Linie völlig verantwortungslos. Sie werden wahrscheinlich mehr Erfolg im Geschäft haben, wenn Sie ihnen das Gefühl geben, dass sie alles haben, was sie brauchen, falls Sie vom Blitz getroffen werden oder in einen Brunnen fallen.

7. Betriebstheorie. Dies ist auch optional. Produziere es und mache einen guten Job, wenn du gefragt wirst, aber füge es nicht automatisch hinzu. Das lädt nur einen ungekünstelten Kunden ein, zu glauben, er wisse, wie das Ding funktioniert, und etwas Dummes zu tun. Er beschuldigt Sie. Oder sie glauben dann genug zu wissen, um alle Details zu erraten. Diejenigen, die wissen, dass sie speziell danach fragen müssen, werden es mit größerer Wahrscheinlichkeit beantworten.

   ol>

   Interne Dokumentation ist ein anderes Thema. Natürlich haben Sie bereits alle vom Kunden bereitgestellten Dateien, wie oben beschrieben, auf Ihrem Computer. Darüber hinaus führe ich ein Protokoll aller relevanten E-Mails, die mit dem entfernten Flaum bearbeitet wurden, sowie aller Spezifikationen, Zeichnungen usw., die der Kunde gesendet hat. Wenn Sie Nachforschungen anstellen oder komplizierte Analysen durchführen mussten, um Entwurfsentscheidungen zu treffen, sollten Entwurfsnotizen vorhanden sein, die beschreiben, was Sie getan haben, warum, was Sie gefunden haben und wie Sie dies verwendet haben, um zu den Schlussfolgerungen zu gelangen, die Sie getroffen haben.

Jede vertragliche Vereinbarung nach Wahl oder Angebot enthält normalerweise eine Liste der Ergebnisse beider Parteien mit einem Masterplan mit wichtigen Meilensteinen. Für ein Entwurfs- und Produktionsprojekt müssen die Ergebnisse aus Spezifikationen bestehen und können aus einer Entwurfsprüfung mit bestehen Prototypenlieferung für Aussehen und behördliche Tests. Die endgültige Funktionsbereitstellung hängt vom Zeitplan mit einer Person ab, die für die Prüfung des Entwurfs (oder die Validierung) oder die DVT anhand der Spezifikationen des Entwurfsprodukts verantwortlich ist. Konstruktionsdetails oder Produktionszeichnungen sind normalerweise die einzige Verpflichtung, aber Quellcode und Konstruktionstheorie können gegen eine zusätzliche Gebühr angefordert werden, es sei denn, dies ist Teil des SOR oder der Anforderungserklärung.

Wenn es sich nur um eine informelle Vereinbarung handelt, sollte die Kommunikation erfolgen zum gegenseitigen Nutzen und alles ist verhandelbar.