In welcher Grammatik soll ich meine Spezifikationen schreiben?

21

Wir schreiben derzeit funktionale und technische Spezifikationen in einem zweispaltigen Format. Zusammenfassungssatz und technisches Detail. Die Details beziehen sich oft auf einen Anhang mit Diagrammen, Layoutdesigns ect.

Ich kämpfe jedoch mit der Zeit, in der ich es schreiben muss:

In der Vergangenheitsform, als wäre die Arbeit erledigt, bemühe ich mich, die wichtigsten Erweiterungen der aufregenden Arbeit aufzuzeigen. Future Tense wie es sein muss X fängt an wie eine To-Do-Liste zu klingen oder Tense neutral, sehr hart, wie es entweder getan werden muss oder getan wird.

Um weitere Verwirrung zu stiften, kann diese Spezifikation von Personen gelesen werden, die kein Englisch als Muttersprache haben.

documentation specifications writing John
quelle

Antworten:

12

Davon haben wir an meinem letzten Arbeitsplatz reichlich.

Die Produktmanager haben beschlossen, die Gegenwart zu verwenden, um zu beschreiben, was getan werden muss , wie:

Der Benutzer sendet eine Bestellung. Das System sendet eine Bestätigungsnachricht.

Leider wurde die Beschreibung der Voraussetzungen auch in der Gegenwart vorgenommen, wie:

Der Benutzer legt einen Artikel in den Warenkorb und gibt die Menge an.

Dies hat für mich viel Verwirrung gestiftet, da nicht klar ist, was bereits ist und was noch kommen wird. Ich habe versucht, sie dazu zu bringen, eine Zukunftsform zu verwenden, aber sie mussten sich nie ändern. Persönlich konnte ich mich in all meinen zwei Jahren dort nicht daran gewöhnen. Es ergibt einfach keinen Sinn, hört sich so an, als ob jemand die Zeitformen der Sprachen nicht beherrscht.

Deshalb:

  • Verwenden Sie eine Gegenwartsform für das, was bereits existiert

  • Verwenden Sie eine Zeitform für das, was getan werden muss. Beschäftige die Welten "sollte", "muss", "wird".


quelle
Der wichtige Schritt, an den Sie sich erinnern müssen, ist die Überprüfung der Spezifikation. Achten Sie darauf, den Wortlaut von künftig auf aktuell zu setzen, wenn er fertig ist.
Ben L
@ BenL: Nein, das ist falsch. Die Zeitform wird verwendet, um eine korrekte Implementierung bereitzustellen, ohne den Status der Implementierung anzugeben. In diesem Fall wird die Zeitform verwendet, um einen zukünftigen Anwendungsstatus und keinen zukünftigen Implementierungsstatus anzugeben. Nebenbei bemerkt, ist es erwähnenswert, dass der hier befürwortete Ansatz auch von den meisten RFCs verwendet wird. In RFC 2119 finden Sie Erläuterungen zu den Begriffen Muss / Erforderlich / Soll (nicht), Soll / Empfohlen (nicht) und Möglich / Optional.
Brian
5

Gegenwart scheint mir gut zu sein.

  1. Voraussetzung: Foo befindet sich im Zustand X
  2. Operation: dies und das passieren
  3. Nachbedingung: Foo befindet sich im Zustand Y

alle diese sind in der Gegenwart.

Oder wenn es ein "Projektstatus" ist

  1. Version 10: verfügt über die Funktionen A, B, C und D

  2. Version 10.1: enthält Verbesserungen an A. Behebt den Fehler 1049 in B. Fügt die neue Funktion E hinzu.

Goldesel
quelle
2

Spezifikationen sind Anweisungen. schreibe sie in der Gegenwart. so was.

Steven A. Lowe
quelle
1

Wenn ich Entwürfe für Software erstelle, bevorzuge ich die Gegenwart, auch wenn ich die Entwürfe erst erst erstelle, bevor die Software existiert. Auch nachdem eine Softwareanwendung aus dem Entwurf implementiert wurde, ist der Entwurf immer noch relevant und ein wichtiges Dokument. Es ist durchaus möglich, dass ein Designdokument nach der Implementierung der Software für einen längeren Zeitraum relevant bleibt als vor der Implementierung.

Dan Stevens
quelle