Zarządzanie pisaniem specyfikacji

9

Po prostu nie wyobrażam sobie pisania oprogramowania bez specyfikacji. Bez względu na to, jak szkicowy lub na wysokim poziomie, specyfikacja jest ważna, aby wyjaśnić programistom bez wiedzy o tym, jakie są funkcje programu.

Problem polega jednak na tym, że jest to obywatel drugiej kategorii w całym cyklu tworzenia oprogramowania; kiedy rozwój odbiera parę, jest zaniedbywany. Ale gdy pojawią się spory, programiści, testerzy i sprzedawcy będą starali się znaleźć specyfikację uzasadniającą ich podstawy.

Stanie się co najmniej jeden scenariusz:

  1. Specyfikacji nie można odzyskać, nikt nie wie, gdzie jest specyfikacja
  2. Różne wersje specyfikacji pochodzą z różnych źródeł; trudno jest ustalić, która wersja jest najnowszą wersją lub czy dostępna jest najnowsza wersja.
  3. Specyfikacja jest niekompletna, brakuje niektórych części dokumentów, do których się ona odnosi.

Dlatego zarządzanie specyfikacjami jest ważne i równie ważne jest to, że każdy ma tylko jedno pojedyncze źródło specyfikacji.

Jak zarządzasz specyfikacjami? Próbowałem zachęcić wszystkich do korzystania z Dokumentów Google, ale wszyscy wyrazili sprzeciw. Wszyscy są zbyt przywiązani i zakochani w programie Microsoft Word, który - ich zdaniem - jest bardzo łatwy w użyciu, bardzo łatwo wstawić obraz, bardzo łatwo wpisać równanie i tak dalej.

Jak przekonać ich, że udostępnianie MS Word jest po prostu okropne?

specifications Grawiton
źródło

Odpowiedzi:

6

Jak przekonać ich, że udostępnianie MS Word jest po prostu okropne?

Nie marnuj czasu.

Pierwszy. Specyfikacja powinna być w postaci zwykłego tekstu (naprawdę) i pod kontrolą kodu źródłowego. Zastosowanie Markdown lub RST lub inne narzędzie lekkie markup produkować PDF lub HTML strony. Zwykły tekst.

Druga. Weź różne źródła. Scal je. Napisz własny dokument końcowy.

Kiedy sprzeciwiają się, mają dwie możliwości.

  1. Użyj Dokumentów Google (lub narzędzia do kontroli kodu źródłowego), aby edytować swoją wersję.

  2. Nadal przesyłaj zmiany, które edytujesz, filtrujesz i przekształcasz do końcowego dokumentu.

Wolę # 2. Ktoś musi „posiadać” specyfikację. A grupa ludzi (w stylu wiki) prowadzi do debat i wojen o zmianę, dokumentów pobocznych i rozmów offline i tym podobnych.

S.Lott
źródło
1
+1 i pamiętaj zasadę najmniejszej mocy - każdy, kto chce fantazyjnej wersji w edytorze WYSIWYG, może po prostu skopiować renderowany znacznik.
l0b0
@ l0b0: Ładny link.
S.Lott,
6

Nie sądzę, że jest to kwestia „narzędzia”, ale raczej kwestia „procesu” (lub braku procesu).

Prawdopodobnie masz już proces wydania oprogramowania (test jednostkowy, test integracji, list wydania, dostawa itp.), Musisz również wdrożyć proces dokumentacji.

  • Kto napisze specyfikacje? Kto zamierza je aktualizować lub utrzymywać?
  • Kto przejrzy specyfikacje?
  • Kto zatwierdzi specyfikacje? Architekt, lider projektu, QA?
  • Jak przechowywane są specyfikacje?
  • Kto dopilnuje, aby nie były używane przestarzałe wersje?
Xavier T.
źródło
2
+1: problemy z narzędziami są często objawami problemów z procesem.
S.Lott,
mamy proces, ale ludzie po prostu uwielbiają narzekać, że ten proces nie działa i skracają rogi, gdy tylko jest to możliwe.
Graviton
@Graviton: Twoim głównym problemem jest prawdopodobnie to, że kierownictwo nie widzi wykorzystania dokumentacji, a zatem nie egzekwuje ścisłych zasad. Jeśli chcesz coś poprawić, prawdopodobnie będziesz musiał im pokazać, jak ważne jest to.
Xavier T.
4

Pewien rodzaj kontroli jest zdecydowanie wymagany.

Musi być wersjonowany i podpisany, a proces ten musi być rygorystyczny.

W zbyt wielu miejscach wypisywanie się jest zaniedbywane, a to prowadzi do walk z bułkami.

Lokalizacja nie ma znaczenia, o ile można ją śledzić

  • Sharepoint
  • bezpieczny, współdzielony dysk z kopią zapasową
  • Widziałem, że niektóre miejsca używają kontroli kodu źródłowego !!

Ale co ważniejsze, musisz zaangażować wszystkie zaangażowane osoby oraz 1 lub 2 osoby, które są odpowiedzialne za zarządzanie zarówno dokumentem, jak i podpisaniem go np. kierownik projektu.

ozz
źródło
+1, zdecydowanie zalecam przeniesienie dokumentu specyfikacji do kontroli źródła, jeśli nic innego nie pomoże. Zaletą jest to, że masz historię wersji. Nawet jeśli nie możesz wykonać różnic wersji (chyba że znajdziesz wtyczkę, która może różnicować pliki Worda), możesz wyodrębnić wszystkie wersje i zobaczyć, co się zmieniło. Może to być BARDZO przydatne w sporze dotyczącym specyfikacji. Bardzo dobrze jest też podpisać się. Nie można również wystarczająco podkreślić znaczenia zaangażowania wszystkich w proces (aby nikt nie mógł powiedzieć „kiedy to postanowiono?”).
FrustratedWithFormsDesigner
0

MS Word doskonale nadaje się do tworzenia specyfikacji. Zarządzamy naszą w SharePoint, który obsługuje również wersjonowanie. Jeśli nie masz pod ręką SharePoint lub innego produktu do zarządzania dokumentami, Dokumenty Google są w porządku (możesz teraz przesyłać pliki .doc / .docx bez konwersji ich do formatu Dokumentów Google). Lub, jak sugerują inni, możesz nawet przechowywać je w systemie kontroli wersji kodu źródłowego (jeśli osoby tworzące specyfikacje mają dostęp do tego systemu).

Marcie
źródło
0 
 > How to convince them that MS Word is just terrible for sharing?

nie można łatwo porównać, jaka jest różnica między dwoma instancjami w systemie kontroli wersji.

Z tego powodu nie lubię specyfikacji słów. Ale ponieważ jest to polityczna decyzja o użyciu specyfikacji słów, mamy jako pierwszą stronę „informacje historyczne” z tymi kolumnami:

numer wersji (dotyczy weryfikacji produktu), autor, data, opis

k3b
źródło