Pisanie dokumentacji do aplikacji na Laravel

Napisałem ostatnio u siebie w pracy bardzo prostą aplikację w Laravel. Logowanie po ldap, formularz do wyszukiwani z bazy danych oracla klientów, kilka widoków i cache w plikach.

Aplikacja działa już kilka tygodni, jednak dyrektor wpadła na pomysł, że trzeba do tego dołączyć dokumentację. Jako programista jestem raczej amatorem i większość tego co robię nie opuszcza mojego komputera. Nie pracowałem też nigdy jako programista w żadnym korpo, czy nawet u Januszów, wiec tym bardziej nie pisałem technicznej dokumentacji projektu.
Dostałem na wzór dokumentacje innego systemu w firmie, ale tam jest wszystko autorskie i ktoś opisał, każdy plik i funkcję jaka tam się znajduję.

Jeżeli przyszło Wam pisać prostą aplikację opartą na frameworku to na ile rozpisywać się na temat działania samego frameworka, a na ile tylko własne elementy? Jeżeli oparłem autoryzację o ldap, to opisywać cały mechanizm logowania, czy tylko własne skrypty?
Podobnie z bazą danych, gdzie Laravel nie wspiera z marszu Oracla, jak również i do Apache musiałem coś doinstalować.

Cześć.
Najpierw musisz się zastanowić nad tym jak chcesz zbudować dokumentacje.
Czy macie u siebie w firmie jakieś inne dokumentacje? Dzięki temu będziesz mógł się wzorować na innych dokumentacjach.

Dokumentacje pisane w mojej firmie są budowane dla pracowników firmy.
Budujemy schemat blokowy z działaniem aplikacji, czyli cały proces, z pokazaniem jak jest zbudowana aplikacja.
Każdy ten blok posiada link do strony, w której jest opisany schemat działania (np. po co to jest, zależności oraz opis działania. Na dole jest omówiony kod)
Początek dokumentu

Na początku dokumentacji powinny się znaleźć:
copyright (najlepiej zwrócić się do działu prawnego firmy o opracowanie dokładnego sformułowania)
spis treści
opcjonalnie: spis ilustracji (dla użytkownika może być wygodne, jeśli będzie mógł znaleźć konkretny diagram, bez zastanawiania się w jakim powinien być rozdziale)
wstęp.
Wstęp powinien informować:
jaki produkt opisuje dokumentacja
dla kogo dokumentacja jest przeznaczona
co dokumentacja zawiera (bardzo ogólnie)
jakie konwencje są stosowane w dokumentacji (np. jaka czcionka jest stosowana dla zamieszczonych w dokumentacji fragmentów kodu źródłowego).
nagłówek rozdziału głównego
nagłówek podrozdziału
nagłówek pod-podrozdziału
i tak dalej…
„zwykły” tekst
lista numerowana
lista wypunktowana
tekst przesunięty w prawo, stanowiący kontynuację (od nowego wiersza) tekstu z listy numerowanej lub wypunktowanej
fragment kodu źródłowego
podpis pod rysunkiem.

Koniec dokumentu
Na końcu dokumentacji powinny się znaleźć:
załączniki
słowniczek terminów specyficznych dla opisywanego systemu, oraz terminów i skrótów które są używane w dokumentacji, a których użytkownik może nie znać
indeks.

Jeśli jest to dla klienta, którego kod nie interesuje to zbuduj na zasadzie instrukcji.

Dzięki wielkie za odpowiedź, ale jakoś już się z tym uporałem bo deadline wisiał nad głową.

To co opisałeś to ogólna charakterystyka dokumentacji, może źle się wyraziłem, ale chodziło mi bardziej o taką dotyczącą dość prostej rzeczy opartej na frameworku. Prostej ponieważ zaiwrała tylko logowanie poprzez konto domenowe i prosty formularz do przeszukiwania bazy danych i generowania PDFów.

To co zrobiłem to opisałem własne skrypty i bardzo ogólnie zasadę działania tego co robił już framework, a co brało udział w działaniu aplikacji. Po szczegóły kazałem odwoływać się do dokumentacji Laravela bo nie będę przecież przepisywał na nowo wszystkiego wraz ze spolszczeniem (dokumentacja była pisana w języku polskim).

Na wzór dostałem inną dokumentacje, ale dotyczyła ona znacznie bardziej rozbudowanego systemu, w dodatku pisanego 10+ lat temu więc co nieco podpatrzyłem, ale większość napisałem z głowy tak jak uważałem za poprawne.

Aplikacja na szczęście działa już oficjalnie, więc jakoś to poszło :)