dokumentacja aplikacji, jak powinna wygladac? Opcje

[AxZx]

witam

mam przygotowac dokumentacje juz gotowej aplikacji, ale nie wiem za bardzo jak taki dokument powinien wygladac.
czy mozna gdzies znalezc przykladowy konspekt?

chcialbym to w celu edukacyjnym, nie zarobkowym.
pozdrawiam

[kicaj]

Zobacz jak sa dokumentowane dostepne na rynku darmowe frameworki

[sniezny_wilk]

Piszesz kod zgodnie ze obowiązującymi standardami phpDoc i generujesz dokumentację.

[AxZx]

i tylko tyle?
mi nie chodzi o udokumentowanie kodu tak jak to zrobi phpdoc, albo tak jak to robia tworcy frameworkow. moze jest to podobne do tego co daje sie klientowi ale chyba nie dokonca.
framework to jest tylko framework wiec nie bedzie tam opisu funkcjonalnosci dla poszczegolnych uzytkownikow itd.
poszukuje raczej poprawnego konspektu do dokumnetacji dla odbiorcy koncowego danej aplikacji - co ma sie tam znalezc, jaka struktura takiego dokumentu itp.

[sniezny_wilk]

A phpDoc nie wystarczy ?

[AxZx]

a powiedz mi gdzie dokladnie jest opisane jak opisac aplikacje za pomoca phpdoc ?
nie umiem tego znalezc.

[sniezny_wilk]

W tutorials - Quicstart

[empathon]

i tylko tyle?
mi nie chodzi o udokumentowanie kodu tak jak to zrobi phpdoc, albo tak jak to robia tworcy frameworkow. moze jest to podobne do tego co daje sie klientowi ale chyba nie dokonca.
framework to jest tylko framework wiec nie bedzie tam opisu funkcjonalnosci dla poszczegolnych uzytkownikow itd.
poszukuje raczej poprawnego konspektu do dokumnetacji dla odbiorcy koncowego danej aplikacji - co ma sie tam znalezc, jaka struktura takiego dokumentu itp.

Taką dokumentacje nazywamy dokumentacją użytkową. To o czym pisze kicaj i sniezny_wilk to dokumentacja techniczna.
Cytuję za "Inżynieria oprogramowania" Andrzej Jaszkiewicz:

Dokumentacja użytkowa jest przeznaczona dla różnych klas odbiorców. Dwie podstawowe klasy to:

• użytkownicy końcowi
• administratorzy systemu

[...]
Podstawowe składowe dokumentacji użytkowej to:

• Opis funkcjonalny. Jest to wstępna część dokumentacji, która w zwarty sposób opisuje przeznaczenie i głowne możliwości systemu. Opis funkcjonalny powinien dostarczać osobie rozważającej zakup lub wykorzystanie systemu niezbędnych informacji pozwalających ocenić czy system spełnia jej potrzeby. Opis funkcjonalny jest też przydatny początkującym użytkownikom, którzy nie znają jeszcze dobrze możliwości systemu.
• Podręcznik użytkownika. Jest to opis systemu przeznaczony głównie dla początkujących użytkowników. Część ta powinna zawierać informacje o:
  • sposobach uruchamiania oraz kończenia pracy z systemem
  • sposobach realizacji najczęściej wykorzystywanych funkcji systemu
  • metodach obsługi błędów, np. o sposobach odwoływania błędnych operacji wykonywanych przez użytkownika
  • sposobach korzystania z systemu pomocy
  Podręcznik użytkownika powinien przedstawić prosty przykład korzystania z systemu.
• Kompletny opis Jest to część przeznaczona głownie dla doświadczonych użytkowników. Powinna zawierać
  • szczegółowy opis wszystkich funkcji systemu
  • informacje o wszystkich sposobach wywoływania tych funkcji
  • opis formatów danych
  • opis błędów, które mogą się pojawić podczas pracy z systemem
  • informacje o wszelkich ograniczeniach dotyczących np. zakresów danych
• Opis instalacji. Jest to składowa dokumentacji przeznaczona gównie dla administratorów systemu. Powinna zawierać opis procedury instalacji oraz dostrojenia systemu do środowiska, w którym będzie pracować.
• Podręcznik administratora systemu. Część ta powinna opisywać możliwości zmian konfiguracji systemu i sposoby udostępniania systemu użytkownikom końcowym.

[...]
Zarówno całość dokumentacji, jak i poszczególne podręczniki mogą dodatkowo zawierać:

• słownik używanych terminów
• indeks

To tak ogólnie. Chyba mniej więcej widać o co chodzi. Pamiętaj, że takie coś kosztuje i musisz to wliczyć w cenę systemu.

[sniezny_wilk]

@empathon:

chcialbym to w celu edukacyjnym, nie zarobkowym. (...) framework to jest tylko framework wiec nie bedzie tam opisu funkcjonalnosci dla poszczegolnych uzytkownikow itd.

dlatego uważam, że taka dokumentacja będzie na miejscu.

[empathon]

@empathon:
dlatego uważam, że taka dokumentacja będzie na miejscu.

Przeczytaj proszę kolejne zdanie.

poszukuje raczej poprawnego konspektu do dokumnetacji dla odbiorcy koncowego danej aplikacji - co ma sie tam znalezc, jaka struktura takiego dokumentu itp.

Odbiorca końcowy = użytkownik.
Zresztą niech wypowie się sam zainteresowany.

Ten post edytował empathon 5.05.2008, 13:30:42

[AxZx]

wlasnie o to chodzi o czym napisal @empathon za co wielkie mu dzieki:)
phpdoc nie zrobi czegos takiego bo on chyba nie wie do czego ma sluzyc dana funkcja i nie umie opisac uzytkownikow itd.
wiem ze mozna w @description pisac, no ale bez przesady - tam mozna napisac ogolnikowy opis zeby miec rozeznanie w kodzie (jako programista).

ja myslalem zeby opisac to mniej wiecej tak:

• uzyte narzedzia (jaki framework),
• wykorzystane technologie (xhtml, php, css),
• wykorzystane biblioteki (jquery, tinymce itd)
• wzorce projektowe, architektura aplikacji (MVC)
• uzytkownicy systemu (admin, klient)
• funkcjonalnosc dla kazdego uzytkownika

dobrze kombinuje?

[empathon]

wlasnie o to chodzi o czym napisal @empathon za co wielkie mu dzieki:)
phpdoc nie zrobi czegos takiego bo on chyba nie wie do czego ma sluzyc dana funkcja i nie umie opisac uzytkownikow itd.
wiem ze mozna w @description pisac, no ale bez przesady - tam mozna napisac ogolnikowy opis zeby miec rozeznanie w kodzie (jako programista).

ja myslalem zeby opisac to mniej wiecej tak:

• uzyte narzedzia (jaki framework),
• wykorzystane technologie (xhtml, php, css),
• wykorzystane biblioteki (jquery, tinymce itd)
• wzorce projektowe, architektura aplikacji (MVC)
• uzytkownicy systemu (admin, klient)
• funkcjonalnosc dla kazdego uzytkownika

dobrze kombinuje?

Cieszę, że pomogłem. To o czym teraz napisałem będzie raczej modelem systemu z określeniem standardów i zakresu użycia gotowych komponentów. Bliżej temu do specyfikacji nie dokumentacji.
Myślę, że zainteresuje Cię książka z której cytowałem w poprzednim poscie. Kosztuje około 22 pln wiec na pewno nie stracisz

Ten post edytował empathon 5.05.2008, 18:24:34

[AxZx]

aha
czyli nadal bladze. wlasciwie to chyba musze zapytac prowadzacego cwiczenia czego oczekuje:)
oczekuja cos czego nie ucza - tak to juz bywa, wiec musze sam szukac, a wychodzi na to ze nawet nie wiem czego szukac.

ksiazke napewno kupie.

pozwole sobie jeszcze na zadanie pytan pomocnicznych

kto robi specyfikacje, a kto dokumentacje?
kiedy powstaje specyfikacja, a kiedy dokumentacja (w stosunku do powstania aplikacji, w stosunku do systemu informacyjnego /SI/)?

[empathon]

Napisz może dokładnie co masz zrobić.

Specyfikacja powstaje w fazie strategicznej projektu czyli przed przystąpieniem do właściwej, w rozumieniu programistycznym, realizacji.
Dostarcza jej zleceniodawca/ powstaje ona w ramach wywiadu z użytkownikiem końcowym/ bądź w przypadku projektu wewnętrznego jest przełożeniem założeń inicjatora. Określa ona docelową funkcjonalność na podstawie wymagań. Nie określa ona sposobu implementacji.

Dokumentacja tworzona jest w czasie trwania całego projektu. Zarówno techniczna jak i użytkowa. Jej częścią może być specyfikacja.

Zagadnienie jest bardzo bogate a ja nie czuje się w nim ekspertem. Nie ma chyba sensu przepisywać książki

[AxZx]

dzieki. w takim razie ide do ksiegarnii:) skoro sa tam takie zagadnienia opisane.
a jest moze cos podobnego tylko ze nowsze? ta ksiazka ma 11 lat, w tym czasie metody tworzenia aplikacji mogly sie zmienic pod wplywem szybko rozwijajacego sie rynku aplikacji internetowych.

[empathon]

Inżynieria oprogramowania opisuje cały proces produkcji oprogramowania. Tworzenie dokumentacji, specyfikacji jest tylko jej częścią.

Wracając do problemu. Myślę, że wszystko zależy od tego kim jest użytkownik końcowy. Jeśli jest nim np. programista jak w przypadku wspomnianych przez kicaj framework to z pewnością dokumentacja użytkowa pokrywać się będzie z techniczną.

Ten post edytował empathon 5.05.2008, 20:56:14