Co wedlug was powinna posiadac dobra dokumentacja aplikacji? Czym sie kierujecie piszac taka dokumentacje? Co jest najwazniejsze? Czy korzystacie z jakis szablonow?

Ja np.: pisząc dokumentację kieruję się opisami funkcji.
Jeśli klient wyamga aby dokumentacja była w osobnym pliku tekstowy zbieram wszystkie komentarze funkcji jakie piszę w czasie tworzenia kodu i w pliku je trochę rozszerzam o szczegóły, które w komentarzach do kodu były zbędne.
Jesli chodzi o schemat komentarzy to u mnie wygląda tak:

[PHP] pobierz, plaintext 
/**
* Zbieranie danych o kategoriach
*
* @param array $params tablica filtrów wyszukiwania
* 
* @return bool/array FALSE jeśli brak kategorii, jesli kategoria istnieje - tablica z danymi
*/
[PHP] pobierz, plaintext 

Wydaje mi się, że to standardowy komentarz do funkcji

no i przepuszcza się takie pliki przez jakiś generator dokumentacji, który automatycznie ci wygeneruje pliki w formacie HTML czy innym na podstawie komentarzy w kodzie (jaki konkretnie generator? To już zależy od języka programowania, ale ogólna zasada chyba jest taka, że bierzesz nazwę języka programowania i dodajesz słowo doc - np. JSDoc, JavaDoc itp. przypuszczam, że i jakies PHPDoc może istnieć).

PrinceOfPersia nie pomyliłeś się istnieje http://www.phpdoc.org/ ale zasada jest w zasadzie wszędzie taka sama, wystarczy się raz tego nauczyć a potem już to robi się automatycznie

Istnieje jeszcze dosyć dobra alternatywa dla PHPDoc
http://www.apigen.org/

Właśnie zapoznałem się z "apigen" i calkiem przyjazne jest.