Jak udokumentować projekt, który jest już opracowany?

Chciałbym wiedzieć, jakie opcje są dostępne do dokumentowania projektu, który został już opracowany, ponieważ programiści, nad którymi pracowali, nie napisali ani jednej strony dokumentacji.

Projekt nie zawiera żadnych innych szczegółów poza wieloma stronami skryptów z funkcjami napisanymi i zmodyfikowanymi przez programistów, którzy pracowali nad tym projektem przez ostatnie 2 lata. Mam tylko schemat bazy danych i pliki projektów. Chciałbym wiedzieć, czy istnieje jakiś sposób na zorganizowanie tego projektu i udokumentowanie go, aby był on pomocny dla programistów, którzy będą pracować nad tym projektem w przyszłości.

Projekt został opracowany przy pomocy PHP i MySQL. Funkcje są źle skomentowane, więc nie mogę uzyskać dobrych wyników, gdy uruchomię to z doxygen.

Kto będzie czytał dokumentację? Do czego będzie używana dokumentacja? To są najważniejsze pytania, na które należy odpowiedzieć. Na przykład dokumentacja dla programistów konserwacji skupiałaby się bardziej na strukturze, podczas gdy dokumentacja dla programistów integrujących się z produktem koncentrowałaby się bardziej na usługach internetowych i strukturze bazy danych.

Zasadniczo rób tyle dokumentacji, ile jest wymagane i nie więcej. Wiele organizacji wymaga dokumentacji, ponieważ ktoś nalegał, że jest to najlepsza praktyka, ale dokumentacja ostatecznie gromadzi kurz.

Zakładając, że ludzie faktycznie skorzystają z dokumentacji, nie próbuj przechwytywać kodu i bazy danych na najmniejszy poziom. Programiści sprawdzą kod pod kątem drobiazgów. Zamiast tego skup się na szczegółach, które nie są widoczne w kodzie , na przykład:

1. Te przypadki użycia produkt spełnia. Może to być trudne, biorąc pod uwagę wiek produktu, ale uchwycenie tego, co produkt ma zrobić, daje czytelnikom i testerom nietechniczny kontekst. Kim są konkurenci na rynku (jeśli istnieją)? Czy coś jest wyłączone z zakresu produktu?
2. Wszelkie wyraźne wymagania niefunkcjonalne . Na przykład, czy produkt został napisany do obsługi określonego wolumenu? Ile lat mogą mieć dane? Gdzie jest używane buforowanie? W jaki sposób użytkownicy są uwierzytelniani? Jak działa kontrola dostępu?
3. Schemat kontekst pokazuje interakcję z innymi systemami, takimi jak bazy danych, źródła uwierzytelniania kopii zapasowej, monitorowania i tak dalej.
4. (Jeśli są znane) Ryzyko i sposób ich ograniczenia wraz z rejestrem decyzji . Z perspektywy czasu jest to prawdopodobnie trudne, ale często decyzje krytyczne wpływają na projekt. Uchwyć wszystko, co znasz.
5. Typowe wzorce projektowe lub wytyczne projektowe . Na przykład, czy istnieje standardowy sposób dostępu do bazy danych? Czy istnieje standard kodowania lub nazewnictwa?
6. Krytyczne ścieżki kodu , zwykle przy użyciu schematów blokowych lub aktywności UML lub diagramów sekwencji. W projekcie może nie być żadnych, ale są to zwykle artykuly użytkowników biznesowych.

Nawet jeśli wszystkie te informacje nie są dostępne, zacznij już teraz . Programiści, którzy przyjdą po tobie, podziękują ci.

Dobre zautomatyzowane testy jednostkowe lub przypadki testowe mogą być również użyteczną dokumentacją, choć trudną do uzyskania dla osób mniej technicznych.

Brzmi również tak, jakbyś musiał dokonać zmiany kulturowej, aby uwzględnić dokumentację . Zacznij od małego, ale najlepiej, aby projekt nie był „gotowy”, dopóki nie będzie miał co najmniej minimalnego poziomu dokumentacji. Jest to prawdopodobnie najtrudniejszy krok, ponieważ powyższe to rzeczy, które możesz kontrolować. Jest to coś, w co inni muszą kupić. Jednak może być również najbardziej satysfakcjonujący, szczególnie jeśli następny projekt, który wykonujesz, zawiera dobrą dokumentację.

W przeszłości radziłem sobie z taką sytuacją, siadając z różnymi właścicielami produktów lub zaawansowanymi użytkownikami, przeglądając ich podstawowe przypadki użycia i dokumentując je za pomocą zestawu testów. Możesz użyć ich jako podstawy dla systemu, gdy zaczniesz wprowadzać zmiany w przyszłości. Pomoże to również zidentyfikować obszary systemu, które nie mają właściciela ani przypadku użycia i mogą zostać potencjalnie usunięte.

Wszystko zależy naprawdę od wielkości systemu. Jeśli jest to złożony system z wieloma różnymi zainteresowanymi stronami, możesz stworzyć schemat komponentu wysokiego poziomu, wyszczególniający istniejące możliwości i gdzie są one spełnione. Może to być bardzo pomocne w identyfikowaniu problemów architektonicznych w projekcie systemu.

Zasadniczo sugeruję unikanie przestarzałej dokumentacji, ponieważ będzie ona przestarzała i w przyszłości będzie prowadzić do nieobecności programistów. Zawsze staram się tworzyć żywą dokumentację w formie testów, które będą utrzymywane w miarę ewolucji systemu.

Po pierwsze, kto jest twoją grupą docelową? Przyszli programiści lub inni przedsiębiorcy? Mając na uwadze odpowiedź na to pytanie:

Jak powiedzieli inni, opis na wysokim poziomie jest pierwszą rzeczą, której potrzebujesz. Wyjaśnij, co system próbuje zrobić w szerszym schemacie rzeczy. Wyjaśnij, na czym działa, jak pasuje do sieci i jak rozmawia z dowolnym innym systemem. Następnie przeglądałem każdy ekran, zrzuty ekranu i szybko wyjaśniałem, co robi ekran i jak wchodzi w interakcje z innymi częściami systemu. Jeśli jest to dla programistów, rozmawiaj tak, jakbyś po raz pierwszy wyjaśniał im aplikację. W końcu o to chodzi w dokumencie (zakładam).

Wszelkie skomplikowane przetwarzanie lub logika użyłbym diagramu stanu, schematu przepływu danych lub diagramu sekwencji. Zdecydowanie wykonaj diagram jednostki, a następnie projekt schematu DB (dwie różne rzeczy!). Być może podstawowy diagram klas, ale upraszczając, zwróć uwagę na najważniejsze rzeczy, które są interesujące, deweloperzy mogą to zrozumieć, patrząc na kod.

Jeśli masz problemy z rozpoczęciem pracy, udawaj, że w pokoju obok ciebie jest inny programista, który nie zna się na rzeczy na temat systemu, jestem dość niecierpliwy i muszę po prostu poznać jego istotę. Następnie zacznij wyjaśniać i zapisz to, co mówisz :)

Wszystkie poprzednie sugestie są dobre, ale rozważę również zbadanie, czy twoja społeczność użytkowników samodzielnie stworzyła dokumentację ad-hoc. W twoim pytaniu nie określono, czy jakakolwiek wersja Twojego „produktu” (istniejąca od dwóch lat) została kiedykolwiek wydana użytkownikom. Jeśli był w użyciu i nie ma oficjalnej dokumentacji, to albo dokumentacja nie była potrzebna, albo istnieje gdzieś „nieoficjalna” dokumentacja, która może być szczątkowa, ale prawdopodobnie również postrzegana przez użytkowników jako niezbędna. Spróbuj przeszukać sieć w poszukiwaniu artefaktów, które mogą reprezentować kluczowe interfejsy API, przeszukaj fora, zapytaj zaawansowanych użytkowników oraz przeszukaj strony z pytaniami i odpowiedziami. Jeśli to możliwe, spróbuj napisać dokumentację spełniającą potrzeby techniczne lub biznesowe.

Pytanie brzmi: czy chcesz udokumentować to, co jest teraz, czy tak, jak powinno być?

Z twojego pytania przeczytałem, że myślisz o dokumentacji API, a nie o dokumentacji użytkownika, a kod może nie jest tak dobrze utrzymany i tajemniczy.

Obawiam się, że jeśli teraz udokumentujesz, skończysz wyrzucaniem większości swojej pracy, gdy kod zostanie ponownie opracowany.

Przyjąłbym następujące podejście:

• uczynić dokumentację niepotrzebną w jak największym stopniu, stosując się do wspólnych najlepszych praktyk. Wybierz dobre nazwy klas, nazwy metod, nazwy zmiennych, które możesz intuicyjnie zrozumieć
• rozbić ogromne klasy potworów i / lub funkcje tam, gdzie ma to sens
• używaj komentarzy PHPdoc - możesz używać narzędzi do tworzenia dokumentacji API
• napisz testy: Testy pomogą ci zrozumieć lub zdefiniować, co powinien zrobić kod.

Teraz nadal masz rzeczy nieudokumentowane: mogą to być ogólne koncepcje, architektura itp. W tym celu napisałbym dokumentację - ale piszę tylko to, co jest naprawdę przydatne i pomocne.