Jak udokumentować istniejącą małą witrynę internetową (aplikację internetową) wewnątrz i na zewnątrz?

Question

Mamy "aplikację internetową", która została opracowana w ciągu ostatnich 7 miesięcy. Problem polega na tym, że nie było tak naprawdę udokumentowane. Wymagania składały się z małej wypunktowanej listy z pierwszego spotkania sprzed siedmiu miesięcy (jest to bardziej "cel" niż wymagania dotyczące oprogramowania). Zebrano szereg funkcji, które wynikały z małych dyskusji werbalnych lub rozmów.

Deweloper wyjeżdża bardzo szybko. Napisał całą rzecz sam i zna wszystkie dziwactwa i zasady leżące u podstaw każdej strony, ale nikt nie wie tak naprawdę więcej niż strona interfejsu użytkownika; co oczywiście jest łatwą częścią, ponieważ jest intuicyjne dla użytkownika. Ale jeśli ktoś musi naprawić lub dodać do niego funkcję, cała sprawa jest czarna. Kod zawiera kilka minimalnych komentarzy, a dobrą rzeczą związaną z aplikacjami internetowymi jest to, że pasek adresu wskazuje właściwy kierunek w kierunku rozwiązania problemu lub aktualizacji strony.

Ale w jaki sposób programista powinien udokumentować tę aplikację internetową? Jest trochę zagubiony, jeśli chodzi o to, od czego zacząć. Jako programista, w jaki sposób całkowicie dokumentujesz swoje aplikacje internetowe dla innych programistów, opiekunów i użytkowników na poziomie administracyjnym? Jakiego podejścia używasz, gdzie zaczynasz, jakiego oprogramowania używasz, czy masz szablon?

Idea wielkości: wykorzystuje PHP, MySQL i jQuery. Ma około 20-30 plików głównych (frontend), wraz z około 15 dołączonymi plikami i kilkoma folderami niektórych zasobów - więc ogólnie jest to całkiem mała aplikacja. Interfejs ten łączy się z 7 tabelami MySQL, z których każda jest dobrze nazwana, więc myślę, że koniec bazy danych jest dość oczywisty. Istnieje plik config.inc.php z definicjami stałych, takich jak dane użytkownika MySQL, niektóre z/do wiadomości e-mail i adresy URL, które PHP używa do wstawiania do e-maili i stron (względne i bezwzględne ścieżki, zasadniczo). Istnieje trochę AJAX za pośrednictwem jQuery.

Proszę o komentarz, jeśli istnieją inne informacje, które mogłyby pomóc mi pomóc i będę zadowolony, aby edytować je.

---

deweloper pozostawia w piątek. Jednak może poświęcić większość z pozostałych 24 godzin na to zadanie dokumentacji. Więc, tak, rzeczy są ponure, ale 24 godziny to całkiem sporo ... prawda? : - \

Answer 1

Zacznę od wymienienia głównych funkcji, które aplikacja aktualnie implementuje (zaktualizuj początkowe punkty).

Następnie dla każdego punktu wypunktowania zapisz główne wymagania związane z tym punktem.

Dla każdego wymogu, zapisz:

• Anything ekscentryczne temat tego konkretnego wymogu
• Gdzie w kodzie, że wymóg ten jest realizowany (który php, pliki Inc, stoliki)

ten da ci coś z hierarchii identyfikowalności

Funkcja => Wymaganie => Implementacja

Zapewni to także dobre ramy do przepychania wspomnień i zapisywania gotcha.

Następnie skomentuj każdą stronę php i inc.

Zacznij od nagłówka, który określa cel i wymagania, które zostały spełnione z poprzedniej listy (odwrotna identyfikacja od kodu do wymagania).

Przejrzyj każdy plik php/inc i skomentuj główne działania/decyzje/pętle wskazujące, co próbują osiągnąć oraz wszelkie założenia projektowe, które są przyjmowane (np. "Zakłada się, że dane wejściowe zostały zatwierdzone w poprzednim kroku") .

Podczas komentowania kodu źródłowego można użyć narzędzia takiego jak PHPDoc, aby móc generować dokumentację z komentarzy.

Answer 2

Jednym ze sposobów może być zorganizowanie serii przekazanych spotkań. W tych programista musiałby wyjaśnić kod każdej sekcji.

Mógł napisać kilka uwag w przygotowaniu, ale posiadanie innych programistów może również zająć minuty, aby pomóc im zrozumieć kod. Również te spotkania byłyby okazją do zadawania pytań na temat aspektów, które nie są jasne.

Nie należy wykonywać całej witryny za jednym razem. Podziel go na dwie mniejsze części zgrupowane w jakiś sposób - według funkcji lub obszaru. Oznacza to, że twoi inni deweloperzy nie są bombardowani za dużo informacji za jednym razem, pierwotny programista może skoncentrować się na jednym obszarze w czasie i masz szansę na obserwację po spotkaniu.

Nawet jeśli nic nie "zacznie" od razu, pewna znajomość witryny pojawi się po jej ponownym odwiedzeniu.

Innym podejściem może być stworzenie przez programistę serii krótkich prezentacji na stronie i sposobu jej zbudowania. Może to skłonić go do przypomnienia sobie, dlaczego zastosował podejście, które zrobił. Jest to nieocenione przy przeglądaniu kodu. Jeśli wiesz, jaki problem próbował rozwiązać, jest o wiele łatwiejszy do zrozumienia.