Ukończyłem aplikację internetową, która jest zasadniczo opracowana w PHP i jest po prostu kolejną zwykłą aplikacją internetową. Zwykle po dostarczeniu ostatecznej wersji produkcyjnej przekazuję klientowi dokumentację kodu i informacje o architekturze. Jednak w przypadku tego konkretnego projektu klient nalega na posiadanie pełnych danych wejściowych i wyjściowych dotyczących projektu.

Zastanawiam się więc ... Jakie są obowiązkowe dokumenty techniczne i nietechniczne, które mogę przekazać klientowi oprócz dokumentacji kodu i dokumentacji?

(Fajnie byłoby też uderzyć klienta w różne statystyki i dane dotyczące projektu, aby wiedział, ile pracy wymaga i jak fajny jest ten produkt.)

Myślę, że lista powinna zawierać:

• Wymagania nietechniczne (istniał taki dokument, prawda?)
• Wymagania techniczne
• Dokument „decyzji” (jeśli taki istnieje) wyjaśniający, dlaczego niektóre decyzje zostały podjęte w stosunku do innych. Może to już dotyczyć innego dokumentu dotyczącego wymagań lub architektury, ale zwykle robimy to osobno dla dużych decyzji.
• Kod i inne zasoby (pliki obrazów, CSS itp.)
• Model bazy danych (jako schemat, dokument, cokolwiek)
• DDL, aby utworzyć bazę danych.
• DML do wysiewu bazy danych.
• Dokument wyjaśniający konfigurację aplikacji i podstawowe rozwiązywanie problemów.
• Lista ważnych nazw użytkowników i ich haseł (w przypadku kont administracyjnych), a także instrukcje dotyczące zmiany hasła. Idealnie byłoby, gdyby podczas konfigurowania witryny po raz pierwszy zostali poproszeni o podanie nowego hasła administratora, ale jest to raczej kwestia architektury.
• Wymagania systemowe, a także w przypadku aplikacji internetowych - minimalne wymagania dotyczące hostingu (czy aplikacja wymaga MySQL lub PostgreSQL? Ile pamięci RAM? Itd.)

Nie wszystkie z tych rzeczy mogą być dostępne (lub konieczne) dla każdego projektu, ale myślę, że jest to dobry ogólny przewodnik.

Oprócz naprawdę dobrej odpowiedzi FrustratedWithFormsDesigner chciałbym powiedzieć, co zawierają dokumenty nietechniczne (tak jak to zrobiliśmy):

• dane analizy: co powiedział ci klient, kiedy po raz pierwszy mówiłeś o wymaganiach?

• oferta, którą złożyłeś:

  • dokument wymagań produktu
  • oraz dokument specyfikacji funkcjonalnej

  które razem stanowią rodzaj umowy o tym, co musisz zrobić i czego oczekujesz
  od klienta podczas rozwoju, a także szacowanego czasu i kosztów.

• specyfikacja, w tym protokoły przeglądu, przypadki użycia i plany testów, wyniki testów

• projekt w UML i wszystkie odpowiednie dokumenty

• dokumentacja kodu źródłowego (doksygen lub cokolwiek innego)

• instrukcja obsługi i wytyczne dotyczące instalacji

• ostateczna faktyczna ilość zasobów (czasu i pieniędzy) wykorzystanych w projekcie, dzięki czemu można wystawić fakturę

• niektórzy klienci chcą również protokołów ze spotkań, które stanowią rozszerzenie wspomnianego wyżej „dokumentu decyzji”

Mam nadzieję, że tego właśnie szukałeś.

Postępuj zgodnie z dokumentacją, która ma zastosowanie do twojego projektu, z poniższych. Być może masz już niektóre z nich.

Dokumentacja techniczna:

• Szczegółowe informacje o PHP i informacje o tym, jak jest on użyteczny w projekcie
• Szczegółowe informacje na temat zaplecza i informacje o tym, jak jest on użyteczny w projekcie
• Informacje na temat łączności z bazą danych wraz z odpowiednimi zdjęciami przedstawiającymi przepływ danych
• Informacje o innych językach programowania lub aplikacjach zaangażowanych w projekt, takich jak XML, HTML itp.
• FAQ plik pomocy

Przygotuj dokumenty ze zrzutami ekranu i zaznacz odpowiedni kod (jeśli to konieczne), aby:

• Informacje o aplikacji frontonu, takie jak obiekty lub kontrolki, właściwości obiektów itp.
• Informacje o zapytaniach do bazy danych (jeśli jeszcze nie są obecne)
• Informacje o właściwościach bazy danych, takich jak klucz podstawowy, klucz obcy itp. Oraz o tym, jak zapewniają spójność i dokładność danych.
• Szczegółowy przewodnik po całym projekcie za pomocą zrzutów ekranu z każdego możliwego rodzaju ekranu z wykorzystaniem zarówno interfejsu użytkownika, jak i zaplecza po uruchomieniu go z przykładowymi danymi, bez powtarzania podobnych danych lub ekranu, w logicznej kolejności.

• Wprowadź nieprawidłowe dane i pokaż, że jest to niemożliwe, ponieważ sprawdziłeś poprawność danych w interfejsie użytkownika i zapleczu.
  /* This step is not applicable if you have not used any object for getting direct input from the user like Text Field as it is obvious that you cannot get invalid data through indirect input. */

• Pokaż, że w programie lub kliencie nie ma błędu w programie ani niespójności w danych, wyjaśniając odpowiedni kod.

• Po podaniu przykładowych danych przez interfejs, możesz dołączyć przykładowe zapytania do zaplecza w celu bezpośredniego pobrania danych z serwera, a także dołączyć przykładowe zapytania DML, które mogą pomóc w przygotowaniu istotnych statystyk danych.

Powinieneś je sam sprawdzić przed udokumentowaniem, aby jeśli Twój klient poprosił o wersję demonstracyjną z przykładowymi danymi, możesz pokazać, jak projekt faktycznie działa, a także upewnić się, że kod frontonu ma odpowiednie wiersze komentarza.

• Na koniec podsumuj statystyki, takie jak całkowita liczba wierszy kodu, całkowita liczba dni spędzonych na projekcie, całkowita liczba sprawdzeń projektu, lista wszystkich używanych aplikacji oraz inne informacje techniczne i nietechniczne.

  
  Dokumentacja nietechniczna:

• Szczegóły dotyczące licencjonowania projektu, jeśli dotyczy.
• Handlowe aspekty projektu, jeśli dotyczy.

Uważać

Potencjał dokumentacji, które mogłyby dać klientowi jest praktycznie nieograniczone. Dodatkowy czas potrzebny na wygenerowanie dokumentacji, której jeszcze nie masz, jest nieopłacony.

Dlaczego klient chce tej dokumentacji (ponad kod źródłowy)? Co z tym zrobisz? Dla kogo to jest?

Odpowiedzi na te pytania pomogą zawęzić zakres tego, co należy dostarczyć.

Bardzo ważne jest, abyś ty i klient dokładnie uzgodnili, jaką dokumentację dostarczyć i czy dodatkowe wysiłki zostaną zrekompensowane.

Nie graj w zgadywanie. Większość dokumentacji technicznej byłaby bezużyteczna dla typowego (nietechnicznego) klienta.

Prawdopodobnie podzieliłbym to na kilka kategorii dokumentów:

Przewodniki:

• Instrukcja instalacji, jak to skonfigurować na serwerze.
• Przewodnik administratora, w jaki sposób skonfigurować i uruchomić aplikację w celu uzyskania optymalnej wydajności. Bezpieczeństwo byłoby również czymś, co należy tutaj omówić, tak aby wiadomo było, jakie hasła ma ta aplikacja i które z niej korzysta.

Wsparcie:

• Jeśli występują problemy, jakie procedury byś zaproponował? Czy zapewniasz wsparcie przez jakiś czas? Prawdopodobnie nadal dawałbym przewodnik lub dwa w tym obszarze, aby ktoś inny znał niektóre łatwiejsze rzeczy, takie jak ponowne uruchomienie usług lub ponowne uruchomienie serwera.

Punkty integracji:

• Czy istnieją punkty integracji innych firm dla tej aplikacji, które sprawiają, że jest ona zależna od innych dostawców niż Twój kod?