Dokumentacja techniczna portalu - co zawiera?

[Zetroxos]

Witam

Mam taki problem. Firma z którą współpracuje miała mi dostarczyć specyfikację techniczną portalu który dla mnie wykonała - https://www.dobralogistyka.pl

Portal jest oparty na frameworku COYOTE, a dokumentacja jaką otrzymałem jest po prostu kopią dokumentacji projektowej frameworku COYOTE (wrzuconą do PDF'a), którą można znaleźć tutaj - https://coyote.boduch.net/index.php/Index/Manual

Czy jesteście w stanie mi napisać czy tak powinna wyglądać dokumentacja techniczna portalu internetowego?

Jeśli nie to jak powinna wyglądać?

Z góry dziękuję za pomoc

[Mion]

Z dokumentacja jaką dostałeś - https://coyote.boduch.net/index.php/Index/Manual jest ogólną dokumentacją techniczną oprogramowania MVC wykorzystanego do budowy silnika serwisu dzięki której inny programista powinien się zorientować "jak działa" serwis co możliwa wprowadzanie zmian, rozbudowę itd... Ujął bym to tak kupujesz czerwonego mercedesa wiec nie dostajesz książeczki technicznej do czerwonego Mercedesa, ale ogólnie do danego typu Mercedesa.

Z drugiej strony mógł Byś wymagać by by każda klasa, metoda, funkcja a itd która znajduje się w plikach nie wchodzących w skład danego frameworka była opisana osobno co robi itd = paruset stronicowa książka

---

W wersji elektronicznej coś takiego jak np https://coyote.boduch.net/docs/api/Coyote-F...r_Abstract.html ale tyczące tego o czym pisałem wyżej.

Np z https://www.phpdoc.org/index.php

[Zetroxos]

Z dokumentacja jaką dostałeś - https://coyote.boduch.net/index.php/Index/Manual jest ogólną dokumentacją techniczną oprogramowania MVC wykorzystanego do budowy silnika serwisu dzięki której inny programista powinien się zorientować "jak działa" serwis co możliwa wprowadzanie zmian, rozbudowę itd... Ujął bym to tak kupujesz czerwonego mercedesa wiec nie dostajesz książeczki technicznej do czerwonego Mercedesa, ale ogólnie do danego typu Mercedesa.

Z drugiej strony mógł Byś wymagać by by każda klasa, metoda, funkcja a itd która znajduje się w plikach nie wchodzących w skład danego frameworka była opisana osobno co robi itd = paruset stronicowa książka

---

W wersji elektronicznej coś takiego jak np https://coyote.boduch.net/docs/api/Coyote-F...r_Abstract.html ale tyczące tego o czym pisałem wyżej.

Np z https://www.phpdoc.org/index.php

Generalnie rozumiem, ale wiem że kod bazowy frameworka był zmodyfikowany w wielu miejscach + dodane wiele skryptów zewnętrznych. Czy one nie powinny się znajdować w specyfikacji? Tak jak bym miał ztuningowanego mercedesa.

Pozatym czy w specyfikacji technicznej nie powinno być opisane co się odnosi do jakiego pliku? I opisana struktura serwisu?

[websign]

Nie ma żadnej jasnej definicji czym jest specyfikacja/dokumentacja techniczna i co powinna zawierać dlatego też jeśli oczekiwałeś pełnej dokumentacji całego kodu + opisu jak aplikacja działa, powinieneś był to zaznaczyć jasno w umowie a teraz jak widzisz każdy będzie rozumieć to po swojemu.

[Mion]

jeśli oczekiwałeś pełnej dokumentacji całego kodu + opisu jak aplikacja działa, powinieneś był to zaznaczyć jasno w umowie

Dokładania - takie kwestie należy ustalać jednoznacznie i na papierze , a jak sam nie wiesz co to jest dokumentacja techniczna powinieneś się dowiedzieć, by wiedzieć czego wymagać

Dokumentację techniczną można porównać np:

- zamawiasz jakieś urządzenie powiedzmy tokarkę więc jako dokumentacje techniczną można oczekiwać rysunku technicznego każdej części składowej w twoim wypadku dokładnych opisów, ale nie samego frameworka tylko plików jakie "nie są fabryczne" czyli nie stanowią integralnej części frameworka, klas, metod, czyli całego kodu składowego. Taką dokumentację mogła by być stworzona np w phpdoc, ale to należy jasno określić w umowie. Oczywiście koszt tak udokumentowanego oprogramowania będzie znacznie większy.

----------

https://pl.wikipedia.org/wiki/Dokumentacja_programu

"Tradycyjnie pisanie dokumentacji jest czynnością wykonywaną przez programistów niechętnie, "

[alumilut]

Witam.

Jasne ze wszystko mozna ujac w umowie ale czy naprawde jest to az tak potrzebne zeby wymagac od uslugodawcy az tak szczegulowej umowy bo jak mi sie wydaje to powinno byc jakies zaufanie jak i jakosc uslugi.

pozdrawiam.

P.S.

Mam pary takich na tym forum ktorym zlecam prace i jak do tej pory brak zastrzezen.

do 200 zł. luz

od 200 zł. szczególowe umowy

[INOMan]

W skrócie:

1) Opis wszystkich tabel w bazie danych wraz z opisem kolumn w sensie co tabela reprezentuje, co przechowuje kolumna.

2) Opis wszystkich relacji w bazie danych na diagramach ERD: https://pl.wikipedia.org/wiki/Diagram_zwi%C...zk%C3%B3w_encji

3) Opis wszystkich modeli (Klas PHP) rozszerzających to co jest w bazie danych - czyli Modeli w MVC

4) Opis procedur wykonywanych cyklicznie z crona (w tym backup etc.)

5) Opis procedury instalacji / przeniesienia na inny serwer - wymagania co do konfiguracji serwera etc

6) Opis warstwy prezentacji, tak aby łatwo ją można było zmienić - czyli po prostu opis plików szablonów

7) Inne istotne informacje związane z projektem

[zoreander]

Kiedy baza jest dosyć skomplikowana przydaje się szczegółowy diagram bazy np. https://www.daveegerton.com/assets/images/d...-prestashop.png

Kod dobrze pisany i skomentowany nie wymaga dodatkowej dokumentacji

[Jack Bauer]

Takie pytanie na co komu taka dokumentacja, jak ktoś się zna to zajrzy do kodu, do bazy danych i się zorientuje co gdzie od czego, a gdy ktoś się mało orientuje nawet najlepsza dokumentacja mu nic nie da.

[Mion]

Wyobraź sobie, że kod programu nie koniecznie w PHP, ale np gry w C++ ma 100 plików i 100K linijek kodu .... wtedy wiesz gdzie sobie możesz "zajrzeć"

[Jack Bauer]

Wyobraź sobie, że kod programu nie koniecznie w PHP, ale np gry w C++ ma 100 plików i 100K linijek kodu .... wtedy wiesz gdzie sobie możesz "zajrzeć"

A widziałeś żeby ktoś dołączał dokumentacje do gry ?

[Mion]

Wiesz o czym tutaj mowa - nie sądzę

[zoreander]

Gra w C++ to jednak trochę co innego niż taki portal takiej klasy w którym głównie są standardowe operacje na bazie danych a nie jakieś zawiłe algorytmy które trzeba tłumaczyć wieloma stronami dokumentacji.

[INOMan]

[...]nie jakieś zawiłe algorytmy które trzeba tłumaczyć wieloma stronami dokumentacji.

Zoreander - nawet proste konstrukcje potrafią występować w wielu konfiguracjach i czasem sam komentarz w kodzie nie wystarczy.

Jeżeli ja np. zajmuje się dla jednego z moich klientów od kilku lat programowaniem i rozbudową sklepu internetowego gdzie jest prawie 80 tabel SQL i ponad 200 klas PHP, nie wspominając o innych rzeczach, to uwierz mi - jeżeli ktoś miałby przejąć po mnie ten projekt to bez dokumentacji miałby przesrane.

Ja sam jak mam do jakiejś rzeczy wrócić to czytam o co w niej chodzi/chodziło, ponieważ przy tak dużym projekcie nie ma szans wszystkiego zapamiętać i ogarnąć (+ robię jeszcze inne rzeczy).

[Mion]

przykład to sklep / koszmar SOTE przynajmniej jego starsze wydania