W jakim czasie gramatycznym powinienem napisać swoje specyfikacje?

21

Obecnie piszemy specyfikacje funkcjonalne i techniczne w formacie dwóch kolumn; zdanie podsumowujące i szczegóły techniczne. Szczegóły często odnoszą się do dodatku zawierającego diagramy, projekty układów itp.

Walczę jednak z tym, w jakim czasie napisać to:

Z czasem przeszłym, jakby praca była wykonywana, staram się pokazywać rozszerzenia najważniejszych zakończeń pracy. Czas przyszły, jak to musi zrobić, X zaczyna brzmieć jak lista rzeczy do zrobienia lub Tense neutralny bardzo mocno, ponieważ albo będzie to zrobione, albo zrobione.

Aby dodać zamieszanie, niniejszą specyfikację mogą przeczytać osoby, które nie mają angielskiego jako pierwszego języka.

documentation specifications writing Jan
źródło

Odpowiedzi:

12

Mamy tego mnóstwo w moim ostatnim miejscu pracy.

Menedżerowie produktu wybrali czas teraźniejszy do opisania, co należy zrobić , na przykład:

Użytkownik wysyła zamówienie. System wysyła komunikat potwierdzający.

Niestety opisu warunków wstępnych dokonano również w czasie teraźniejszym, na przykład:

Użytkownik umieszcza przedmiot w koszyku i określa ilość.

Wywołało to dla mnie wiele zamieszania, ponieważ nie jest jasne, co już jest, a co jeszcze przed nami. Próbowałem zmusić ich do używania czasu przyszłego, ale nigdy nie musieli się zmieniać. Osobiście nie mogłem się do tego przyzwyczaić przez wszystkie dwa lata. To po prostu nie ma sensu, brzmi jakby ktoś nie opanował czasów języków.

W związku z tym:

  • Użyj czasu teraźniejszego dla tego, co już istnieje

  • Użyj czasu przyszłego na to, co musisz zrobić. Zatrudnij światy „powinien”, „musi”, „będzie”.


źródło
Ważnym krokiem do zapamiętania jest ponowne przejrzenie specyfikacji. Pamiętaj, aby zaktualizować sformułowanie z przyszłości na teraźniejszość, kiedy będzie gotowe.
Ben L
@BenL: Nie, to źle. Czas ten służy do zapewnienia poprawnej implementacji, a nie do wskazania statusu implementacji. Tutaj czas przyszły służy do wskazania przyszłego stanu aplikacji, a nie przyszłego stanu implementacji. Nawiasem mówiąc, warto zauważyć, że zalecane tutaj podejście jest również stosowane przez większość RFC. Patrz RFC 2119 do dyskusji na temat warunków musi / wymagany / nie może (nie) powinien / zalecane (nie) i może / opcjonalne.
Brian
5

Czas teraźniejszy wydaje mi się dobry.

  1. Warunek: Foo jest w stanie X
  2. Operacja: to i tamto się dzieje
  3. Warunek: Foo jest w stanie Y

wszystkie są w czasie teraźniejszym.

Lub jeśli jest to „stan projektu”

  1. Wersja 10: posiada funkcje A, B, C i D.

  2. Wersja 10.1: zawiera ulepszenie A. Naprawia błąd 1049 w B. Dodaje nową funkcję E.

Dojną krową
źródło
2

specyfikacje są instrukcjami. napisz je w czasie teraźniejszym. lubię to.

Steven A. Lowe
źródło
1

Kiedy tworzę projekty dla oprogramowania, preferuję czas teraźniejszy, nawet jeśli tworzę projekty zanim oprogramowanie istnieje. Nawet po wdrożeniu aplikacji z projektu, projekt jest nadal istotny i ważny dokument. Jest całkiem możliwe, że dokument projektowy może pozostać odpowiedni przez dłuższy czas po wdrożeniu oprogramowania niż przed jego wdrożeniem.

Dan Stevens
źródło