Jakie elementy dostarcza klientowi aplikacja sieciowa? [Zamknięte]

11

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.)

miecznik
źródło
8
To, które elementy obowiązkowe otrzyma klient, zależy całkowicie od umowy i prawa Twojego kraju.
Falcon
2
Dlaczego nie jest to określone w umowie? Cała utworzona dokumentacja powinna stanowić wartość dodaną (lub przynajmniej postrzeganą wartość) dla Ciebie, przyszłych deweloperów lub klienta. Powinieneś (powinnaś) wiedzieć, jaka dokumentacja stanowi wartość dodaną dla ciebie i przyszłych programistów, więc zapytaj klienta dokładnie, jaka dokumentacja jest potrzebna, aby dodać wartość, umieść ją w planie projektu i włącz ją.
Thomas Owens
Których chce klient ? Czy możesz uzyskać informację zwrotną od kierownika technicznego klienta? Ponadto: w jakim sensie twój produkt jest „fajny”? Czy możesz to wyjaśnić?
ZJR

Odpowiedzi:

9

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.

FrustratedWithFormsDesigner
źródło
„Lista ważnych nazw użytkowników i ich haseł (dla kont administracyjnych)” : naprawdę? Deweloper nigdy nie powinien znać żadnego hasła po wydaniu strony, zwłaszcza administracyjnej. Jeśli podasz klientowi listę haseł używanych podczas programowania, możesz być pewien, że klient nigdy ich nie zmieni.
Arseni Mourzenko
4
@MainMa: Zakładam, że klient ma możliwość zmiany haseł i że jedną z pierwszych instrukcji jest „Zmień swoje hasła!”
FrustratedWithFormsDesigner
czy mógłbyś wyjaśnić nowicjuszowi, jakie są „wymagania nietechniczne”?
Abe
1
@Abe: Wymagania nietechniczne powiedzą coś takiego: „Ta aplikacja powinna pozwalać użytkownikowi na zarządzanie własnymi kontami”, a techniczny może powiedzieć „Usługi sieciowe oparte na SOAP udostępnią interfejs, który pozwala aplikacji klienta na zarządzanie kontami użytkowników „.
FrustratedWithFormsDesigner
4

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ś.

Ktoś jeszcze
źródło
3

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.
IndRaj95
źródło
2

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.

Steven A. Lowe
źródło
1

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?
JB King
źródło