Sollten Programmierer auf das Schreiben von Dokumentation achten? Das ist eine scheinbar kleine, aber ziemlich wichtige Angelegenheit. Neben Programmen und Daten umfasst Software auch Dokumentation. Wenn ein Programmierer außerdem nur Programme schreiben kann und seine Ideen nicht angemessen und elegant in der Dokumentation beschreiben kann, dann wird er wirklich ein "Code-Bauer."

Die Bedeutung des Schreibens von Dokumentation

In softwarebezogenen Branchen, ob in der Schule oder am Arbeitsplatz, hat jeder vielleicht bemerkt, dass es neben dem Schreiben von Programmen und dem Zeichnen von Entwurfsdiagrammen,eine weitere wichtige Aufgabe gibt: das Schreiben von DokumentationWarum Dokumentation schreiben? Weil wir zeigen müssen, was wir gemacht haben – nicht nur Kollegen, sondern auch Mitarbeitern in anderen Positionen und sogar Benutzern. Wenn wir nur Programme schreiben können und unsere Ideen nicht angemessen und elegant in der Dokumentation beschreiben können, dann werden wir wirklich "Code-Bauern."

Ich habe bemerkt, dass nur sehr wenige der Kollegen um mich herum hochwertige Dokumentation schreiben können. Herr Kai-Fu Lee, in "The Wave"'sVorwort,sagte: "Ich kenne viele Top-Ingenieure, aber exzellente Ingenieure mit starken erzählerischen Fähigkeiten sind unter denen, die ich kenne, extrem selten."

Tatsächlich können nur sehr wenige der Kollegen, die ich kenne, ihre Ideen klar in der Dokumentation ausdrücken.

1. Wir senden und empfangen jeden Tag viele E-Mails. Ich habe genau hingeschaut und festgestellt, dass der Inhalt vieler E-Mails entweder ungeschickte Sätze hat, viele Tippfehler enthält oder die Zeichensetzung falsch verwendet oder weglässt. Oftmals kann eine E-Mail auf viele verschiedene Arten interpretiert werden, was bei den Leuten ein unklares Gefühl darüber hinterlässt, was sie eigentlich ausdrücken will, was die Arbeitseffizienz stark verringert.
2. Neben Code enthalten Projekte auch eine große Menge Dokumentation. Wenn ich die meisten Dokumente öffne, ist das Erste, was ich empfinde:Unordentliches Layout, falsche Formatierung, unbeholfene Sätze und überall Tippfehler.Auf einen Blick erkennt man, dass der Autor das Dokument nicht ernst genommen hat und auch seine Fähigkeit, Sätze auszudrücken und zu organisieren, schwach ist.
3. In Diskussionen im Projektteam spricht fast jeder darüber, wie man Programme gut schreibt, aber niemand erwähnt, wie man das Schreiben von Dokumentation verbessert. Alle scheinen darin übereinzustimmen, dass es die Pflicht eines Entwicklers ist, Programme gut zu schreiben, und alles andere zweitrangig ist.

Die traditionelle Definition von Computersoftware lautet: Software ist der andere Teil eines Computersystems, der mit der Hardware wechselseitig zusammenhängt. Software umfasst die Gesamtheit von Programmen, Daten und zugehöriger Dokumentation.Beachten Sie, dass hier "zugehörige Dokumentation" erwähnt wird. Wenn die Dokumentation nicht gut geschrieben ist, kann die Software nicht als hervorragend angesehen werden. Tatsächlich gibt es Fälle, in denen die Softwarefunktionen einwandfrei sind, aber aufgrund von Problemen mit der Dokumentation Ausfälle auftreten.

Im Allgemeinen sind im Softwareentwicklungsprozess die wichtigsten Dokumente, die in den verschiedenen Phasen eine Rolle spielen, in der folgenden Abbildung dargestellt:

Es ist erkennbar, dass in verschiedenen Phasen der Software unterschiedliche Dokumente geschrieben werden müssen. In der Planungsphase müssen detaillierte Designdokumente, Dokumente zum Unit-Test-Plan und Dokumente zum Integrationstest-Plan geschrieben werden; in der Entwicklungsphase werden dieselben Dokumente weiterhin benötigt, jedoch als überarbeitete Versionen, weil wir während der tatsächlichen Entwicklung möglicherweise unvernünftige oder schlecht durchdachte Teile des früheren Designs entdecken, was eine Änderung der früheren Dokumente erfordert; in der Testphase müssen Unit-Test-Berichte, Integrationstest-Berichte und Systemtest-Berichte geschrieben werden; in der Software-Release-Phase müssen Installationshandbücher, Benutzerhandbücher, Upgrade-Anleitungen und so weiter geschrieben werden. Diese Dokumente richten sich hauptsächlich an Außendienst-Supportpersonal und Benutzer, daher sollten sie leicht verständlich geschrieben sein, und es darf keinerlei Mehrdeutigkeit geben; andernfalls können Sie nur auf Benutzerbeschwerden warten.

Um gute Dokumentation zu schreiben, müssen wir zunächst ein Missverständnis korrigieren: dass Dokumentation nicht wichtig ist. Dokumentation sollte auf Augenhöhe mit Programmen stehen.

Wie schreibt man qualitativ hochwertige Dokumentation?

Wie können wir also qualitativ hochwertige Dokumentation schreiben? Ich denke, wir können mit den folgenden Aspekten beginnen:

1. Ändern Sie die Einstellung, dass Dokumentation zweitrangig ist. Behandeln Sie im Arbeitsalltag jedes Dokument, das Sie schreiben, ernst.
2. Bei E-Mails: Drücken Sie genau aus, was Sie sagen möchten. Prüfen Sie vor dem Senden einer E-Mail, ob der Inhalt vollständig ist, ob es Tippfehler gibt und ob die Sätze flüssig sind.
3. Befolgen Sie beim Schreiben von Dokumenten strikt die vom Projektteam vorgegebene Vorlage. Führen Sie nach Fertigstellung des Dokuments eine Grammatikprüfung durch, um Tippfehler und grammatikalische Fehler zu korrigieren. Im Allgemeinen haben Sätze mit grammatikalischen Fehlern eine grüne wellenförmige Unterstreichung darunter. Lesen Sie das gesamte Dokument vor der Abgabe noch einmal durch, um zu sehen, ob es Auslassungen oder Mängel gibt.
4. In deiner Freizeit kannst du Bücher oder Artikel lesen, die den sprachlichen Ausdruck und die Schreibfähigkeiten verbessern, und sehen, wie andere ihre Gedanken klar formulieren. Zum Beispiel ist das regelmäßige Lesen von Blogbeiträgen exzellenter Blogger auf CSDN eine gute Möglichkeit, deine Schreibfähigkeit zu verbessern.

Im Allgemeinen spiegelt das Schreiben von Dokumentation, wie bei anderen Tätigkeiten, auch die Einstellung einer Person wider. Hochwertige Dokumentation zu schreiben kann nicht nur dein persönliches Image verbessern (wenn du ein gutes Dokument liest, hättest du dann nicht auch eine höhere Meinung vom Autor?), sondern auch das Image des Produkts in den Köpfen der Kunden stärken. Mit einer solchen Analyse ist es wirklich notwendig, mehr Aufwand in das Schreiben von Dokumentation zu stecken.

Um etwas gut zu machen, müssen wir uns in allen Bereichen anstrengen. Im Prozess der Softwareentwicklung ist es wichtig, guten Code zu schreiben, und ebenso wichtig, seine Gedanken in der Dokumentation klar auszudrücken. "Code" und "Dokumentation" sind wie der linke und rechte Arm eines Menschen; beide müssen sich ausgewogen entwickeln, und wir können uns nicht nur auf eines konzentrieren.

Von:CSDNAutor: Zhou Zhaoxiong