Dlaczego pisanie dokumentów projektowych oprogramowania ma znaczenie

Gratulacje, jesteś kompetentnym niezależnym programistą. Od swoich skromnych początków, być może pracując jako tester, awansowałeś do roli programisty zespołowego, potem starszego programisty, a teraz wykonałeś kolejny, największy z nich wszystkich, skok do bezpośredniej pracy z klientami.

Ale tam, gdzie inne przejścia były liniowe, ta ostatnia była wykładnicza. Podczas gdy w przeszłości dostawałeś rozkazy od pracodawcy, który pracował z klientami lub sam zajmował się branżą oprogramowania, teraz wszystkie te obowiązki, które kiedyś były rozdzielone między testowanie przez ekspertów, zarządzanie programami itp., należą do Ciebie. A teraz pracujesz z klientami, którzy nie działają w branży oprogramowania; są w innej firmie, która potrzebuje oprogramowania i nie mają jasnej i precyzyjnej wizji tego, czego od ciebie chcą. To o wiele większe wyzwanie, niż się wydaje.

*Uwaga:* Tutaj opisuję mniejszych klientów, którzy chcą mieć jednoosobową armię od swojego programisty. Nie jest to jedyna trasa, którą może pokonać freelancer i nie są to jedyni klienci, z którymi współpracujemy w Toptal, ale jest to trasa, którą lubię najbardziej. Oczywiście, jeśli pracujesz w zespole, a nie sam, niektóre z poniższych nie będą miały zastosowania. Na przykład, jeśli używasz metodologii Agile lub Scrum, prawdopodobnie będziesz chciał nieco inaczej ustrukturyzować swoje kamienie milowe.

Wszyscy słyszeliście o najwyższym znaczeniu komunikacji. Nie możesz pracować, otrzymując kilka zdań zwięzłego opisu przez Skype i mówiąc „Do zobaczenia za trzy miesiące, kiedy skończę”. Musisz być w kontakcie ze swoim klientem i na każdym etapie swojej pracy upewnić się, że masz zbieżne wyobrażenia o celu, bo rzeczywiście rzadko zdarza się, aby klient przesłał Ci makiety i szczegółową specyfikację funkcjonalną. Otrzymasz bardzo ogólne pojęcie o tym, co oprogramowanie ma robić, wyglądać i przepływać. Jeśli piszesz aplikację na podstawie pobieżnego opisu, od którego zwykle zaczynasz, prawie nie ma szans, że Twój klient będzie zadowolony z wyniku. Na każdym etapie musisz dążyć do osiągnięcia porozumienia.

Pracując przez lata w firmach, które same działały w branży oprogramowania, gdzie wszyscy w zespole pochodzili z tej samej kultury, mówili tym samym językiem ojczystym, pracowali w tym samym korytarzu, spotykali się codziennie itd., warto było zauważyć, że firma nadal nie otrzymywała tego, czego chciała przez połowę czasu. Nie popełnij błędu: wyzwanie tutaj jest ogromne.

Dlaczego dokumenty projektowe oprogramowania mają znaczenie

Tak więc, kiedy podejmujesz się nowego projektu, zanim jeszcze otworzysz Xcode lub Visual Studio, musisz mieć jasne i uzgodnione cele projektowe . A cele te powinny być określone w dokumencie specyfikacji. Jeśli klient go nie napisał, powinieneś go napisać i przesłać do sprawdzenia, zanim jeszcze otworzysz swoje IDE. A jeśli spotkasz klienta, który szczerze mówi: „Nie mamy czasu na dokumenty projektowe”, powinieneś odejść od projektu , ponieważ masz przed sobą kłopoty. Specyfikacja nie musi być szczególnie długa; może to być tylko kilka stron, ale przynajmniej powinien przedstawiać interfejs użytkownika, zawierać szkielety (jeśli istnieje komponent interfejsu użytkownika) i ustawiać kamienie milowe ukończenia.

Bez tego dokumentu skończysz w pętli złośliwych dwuznaczności, klienci kwestionujący to, co ci powiedzieli lub co im powiedziałeś, ze złością wysyłając wycięte i wklejone poprzednie wiadomości, tłumacząc i kłócąc się, aż nadejdzie czas, gdy klient tego zażąda że wprowadzasz zmiany, aby aplikacja była zgodna z „to, o co faktycznie prosili” i oczekujesz, że dokonasz tych zmian bezpłatnie.

Z tym dokumentem dotyczącym projektowania oprogramowania, będziesz miał odpowiedź na każdą taką sprzeczkę: gdy pojawią się spory, możesz odwołać się do specyfikacji, którą klient zgodził się i podpisał, wskazując, że wypełniłeś ją co do joty. Zamiast gniewnych argumentów wprowadzisz poprawki i wyjaśnienia do dokumentu. Jeśli cokolwiek, klient przeprosi za to, że w pierwszej kolejności dopuścił się niedokładności.

Wszyscy chcemy zadowolonych klientów. Wszyscy chcemy przyjaznej współpracy. I wszyscy chcemy dumy z dobrze wykonanej pracy. Ale tego nie da się osiągnąć, jeśli jest jakaś niejasność co do tego, czym właściwie jest ta praca. Jeśli twój klient mówi, że dokument projektowy to zbyt dużo dodatkowej pracy, twoim zadaniem jest wyjaśnić mu, że prawdziwa dodatkowa praca pojawi się, gdy trzeba będzie wprowadzić poprawki z powodu jakiegoś nieporozumienia. Jeśli klient nadal nalega, abyś awansował bez takiego dokumentu, powinieneś zaakceptować fakt, że masz niewykonalny związek i odejść.

Co właściwie powinna określać specyfikacja projektu oprogramowania?

Powinien to być przynajmniej opis pożądanego wniosku, kryteria ukończenia i kamienie milowe. Pamiętaj, że udostępniasz to, co najlepiej można opisać jako dokument wymagań i funkcji, a nie specyfikację implementacji. I jeśli konkretna implementacja nie jest wyznaczonym celem klienta, sposób, w jaki to zrobisz, zależy od Ciebie.

Interfejs użytkownika

Większość projektów to aplikacje, a nie biblioteki czy frameworki. Ale jeśli zdarzy ci się mieć jeden z nich jako element wynikowy, możesz mieć szczęście, ponieważ interfejs użytkownika jest zdecydowanie najbardziej problematycznym elementem szablonu dokumentu projektowego i prawie zawsze prowadzi do nieporozumień. Wielu klientów przyśle Ci perfekcyjne ilustracje stworzone w edytorze graficznym przez grafika, który nie jest programistą. Ale problem polega na tym, że te ilustracje nie mówią nic o animacjach, stanach sterowania (np. Czy ten przycisk jest wyłączony? Czy znika, gdy nie można go używać?), a nawet o tym, jakie czynności należy wykonać po naciśnięciu przycisku.

Zanim zaczniesz pisać kod za tymi ilustracjami, powinieneś być w stanie odpowiedzieć na wszystkie te pytania. W szczególności powinieneś wiedzieć:

1. Czy kontrolki są zawsze widoczne i/lub włączone? W jakich warunkach zmieniają się ich stany?
2. Wygląda jak mapa bitowa — czy to przycisk?
3. Jakie przejścia zachodzą między tymi stanami i poglądami? A jak powinny być animowane?

Jeśli zależy Ci na wygenerowaniu interfejsu użytkownika dla współbieżności klienta, zrób to samo w odwrotnej kolejności: użyj narzędzia szkieletowego i utwórz kompletny zestaw układów ekranu, w tym wszelkie warianty, które są wyświetlane w widokach w różnych stanach aplikacji. Może to być wyczerpująca i żmudna praca, ale nie pożałujesz — może uchronić Cię przed ponownym pisaniem ogromnej ilości kodu i ponownym tworzeniem interfejsów z powodu drobnych nieporozumień o poważnych konsekwencjach. Jeśli tworzysz podwójną aplikację (np. dla iPhona i iPada), utwórz osobne makiety dla obu.

Ważne są również wymiary ekranu. Istnieją (w chwili pisania) trzy rozmiary ekranów iPhone'a. Oddzielne makiety dla ekranów 3,5” i 4” są prawdopodobnie przesadą, ale być może będziesz musiał je zrobić; w większości przypadków możesz po prostu zmienić proporcje.

Jeśli Twój klient dostarcza Ci grafikę, upewnij się, że są one odpowiednio zwymiarowane i mają odpowiednie proporcje; morfing dowolnej mapy bitowej, która zawiera tekst lub obiekty (takie jak okręgi), wprowadzi zniekształcenia. Jeśli nie pasują, powiedz klientowi, aby odtworzył je z pasującymi rozmiarami. Nie zakładaj, że możesz rozciągnąć ekran powitalny 3,5” na powitalny 4” i po prostu toczyć się z nim.

Funkcjonalność

Kluczowe pytania, które należy zadać w dokumencie projektu aplikacji:

• Co robi aplikacja i jak szybko to robi?
• Jakie są możliwe warunki awarii i jak są one obsługiwane?
• Jakie jednorazowe operacje są wykonywane przy pierwszym uruchomieniu (tj. po instalacji)?
• Jeśli użytkownik tworzy wpisy dowolnego rodzaju (np. zakładki), jakie są ograniczenia?

Uogólniaj te pomysły i bądź tak szczegółowy i dokładny, jak tylko możesz — ponieważ błędy lub nieporozumienia będą oznaczać przepisanie kodu.

Kamienie milowe

Twój szablon specyfikacji powinien zawierać wyraźne kamienie milowe. Jeśli Twój klient pisze projekt funkcjonalny i interfejsu użytkownika, powinieneś następnie uzgodnić zestaw kamieni milowych. Czasami są to również progi rozliczeniowe, ale przynajmniej dostarczają jasnych wskaźników do zakończenia. Kamienie milowe mogą dotyczyć funkcjonalności i/lub komponentów; mogą nawet być oddzielnymi aplikacjami, jeśli koncert obejmuje zestaw elementów dostarczanych. Jeśli to możliwe, kamienie milowe powinny mieć mniej więcej taki sam czas trwania.

Przykład specyfikacji projektu oprogramowania

Tutaj przedstawię przykładową strukturę odpowiedniego dokumentu projektowego. Oczywiście ten szablon należy dostosować do potrzeb. Aby zapoznać się z innym przykładem, zobacz przykładową specyfikację Joela Spolsky'ego, opartą na tym opisie. Nieco inaczej podchodzi do dokumentu, ale podziela podobny sentyment.

Zestawienie celów

Dołącz krótki akapit opisujący projekt i jego odbiorców.

Opis działania

Co robi aplikacja? Jakie stany aplikacji (opisy wysokiego poziomu scenariuszy podstawowych użytkowników) napotka użytkownik?

Na przykład Twój opis funkcjonalny może wyglądać tak:

• Pierwszy bieg
• Tworzenie nowego _____ (gra, wyszukiwanie itp.)
• Operacje
• Zachowanie w tle i na pierwszym planie

Interfejs użytkownika

Dołącz szkielety dla każdej strony, ze szczegółowymi opisami:

• Każda kontrolka, w tym stany (włączone/wyłączone/podświetlone) i operacje.
• Obsługiwane orientacje i przejścia między nimi.
• Reprezentowana funkcjonalność.
• Obsługa błędów.
• Wymiary i ograniczenia.

Oto makiety związane z moją najnowszą aplikacją na iOS, NotifEye:

Jeśli jesteś zainteresowany, wykonałem te makiety za pomocą narzędzia do tworzenia szkieletów firmy Balsamiq.

Na przykład opis interfejsu użytkownika może wyglądać tak:

• Pasek nawigacyjny
  • Lewa kontrolka nawigacji: powrót do strony głównej
  • Pasek tytułu: bieżący ekran lub nazwa operacji
  • Nowy przycisk: utwórz nową Rzecz
• Widok tabeli
  • Sekcja 0: Tytuł sekcji
  • Sekcja 0 wierszy:
    • Kontrola wiersza 0 (np. obraz)
    • Linia tekstu 0
    • Linia tekstu 2

Kamienie milowe

Jak opisano powyżej, terminy realizacji i oczekiwane rezultaty.

Na przykład sekcja kamieni milowych w szablonie dokumentu projektu może wyglądać tak:

1. Aplikacja elewacyjna pokazująca ekran z tymczasowymi przejściami i przykładowymi obrazami/tekstem
2. Protokół komunikacyjny: aplikacja łączy się z siecią/serwerem
3. Funkcjonalny kamień milowy 1: …
4. Aplikacja Alpha (z pełną funkcjonalnością)
5. Stabilność
6. Uwolnienie

Upewnienie się, że dokumentacja oprogramowania pozostaje aktualna

Nie chcę sugerować, że faza projektowania kończy się, gdy Ty i Twój klient uzgodnicie dokument specyfikacji. Zawsze będą szczegóły, których żaden z was nie brał pod uwagę, i zarówno ty, jak i klient, patrząc na wyniki pośrednie, napotkacie nowe pomysły, zmiany w projekcie, nieoczekiwane wady projektu i niewykonalne sugestie.

Projekt będzie ewoluował, a zmiany powinny zostać ujęte w dokumencie. W moim 25-letnim doświadczeniu ani razu nie pracowałem nad projektem, w którym tak się nie stało — w tym z moimi własnymi aplikacjami (tj. gdzie byłem własnym klientem). Nawet wtedy stworzyłem dokument projektowy ze szczegółowymi specyfikacjami i dostosowałem go w razie potrzeby.

Przede wszystkim bądź w kontakcie. Przynajmniej kilka razy w tygodniu skontaktuj się z klientem, zgłoś swoje postępy, poproś o wyjaśnienia i upewnij się, że podzielasz identyczne wizje. Jako papierek lakmusowy dla Twojej komunikacji, postaraj się, aby Ty i Twój klient udzieliliście tych samych odpowiedzi na te trzy pytania:

1. Nad czym deweloper właśnie pracował?
2. Nad czym obecnie pracuje programista?
3. Nad czym deweloper będzie pracował dalej?