Jak mogę udokumentować przeszłe prace innej osoby? [Zamknięte]

Jesteśmy w złej sytuacji, gdy mamy bardzo mało dokumentacji na temat dostosowywania naszych byłych pracowników do krytycznego systemu biznesowego. Wprowadzono wiele zmian w Crystal Reports, jednostkach baz danych oraz zastrzeżonych plikach konfiguracyjnych / programowych dla naszego oprogramowania ERP.

Obecna dokumentacja ogólnie brzmi mniej więcej tak:

Ten program jest uruchamiany przed fakturowaniem. Znane błędy: brak.

Uruchom ten program po zainstalowaniu oprogramowania X.

W tym raporcie zmieniono następujące pola: (bez wyjaśnienia, jak i dlaczego)

Nasz sklep IT jest niewielki, aw przypadku oprogramowania ERP większość pracy została skupiona na jednej osobie (to ja jestem teraz), więc nikt tutaj nie wie, co zrobiliśmy. Dział informatyki i księgowości zna drobiazgi (czasami bardzo pomocne), ale to nie wystarczy.

Innym problemem jest to, że nasz dział księgowości wydaje się uważać za dobrze udokumentowane. To prawda, że ​​prowadziliśmy wiele rejestrów tego, co poszło nie tak , ale bardzo mało wyjaśnia, co (jeśli w ogóle) zrobiono, aby rozwiązać te problemy. Mamy setki artykułów wyjaśniających błędy, ale dokumenty wyjaśniające zmiany (jak pokazano powyżej) są prawie bezużyteczne.

Jak mogę udokumentować wcześniejsze zmiany, gdy nie wiem, co zostało zrobione? Mogę zacząć od udokumentowania tego , co zmieniliśmy: pliki, tabele bazy danych itd., Które musimy mieć, aby system działał. Mogę też udokumentować, co robić ; po uruchomieniu raportów, dlaczego powiedziano ludziom, aby korzystali z raportu / programu X. Ale kiedy jedna z tych niestandardowych rzeczy ma problem, zawsze wracam do pierwszej.

Jak mogę proaktywnie dokumentować te rzeczy dla siebie i innych?

Myślę, że to daremne ćwiczenie. Jeśli to działa, to działa, jeśli nie działa, musisz to naprawić.

Najlepszym sposobem na udokumentowanie starych rzeczy jest praca nad nimi, udokumentowanie tego, co robisz i wyjaśnienie logiki biznesowej (która, jak zakładam, nie została udokumentowana). Będzie to wielka pomoc dla każdego nowego programisty.

Mówiąc o dokumentowaniu starego kodu / rzeczy, ktoś musiał go posiadać. Załóżmy, że to twój obecny menedżer. Może nie mieć pełnej wiedzy technicznej na ten temat, ale będzie wiedział, jakie zmiany zostały wprowadzone. W takim przypadku to nie twoja praca. Być może kierownik może napisać o tym, jakie zmiany zostały wprowadzone. Przydałoby się to zachować jako historię. Jeśli pojawią się takie problemy, możesz zagłębić się w te obszary, które mogą być dla ciebie bardzo pomocne. Ale wchodzenie w kod i dokumentowanie zmian jest dość bezużyteczne IMO i prawdopodobnie niemożliwe.

Porzuć wysiłek dokumentowania zmian .

Zamiast tego zacznij dokumentować, co obecnie działa i jak . Aktualizuj tę dokumentację i aktualizuj ją, wprowadzając zmiany w przyszłości.

Czy masz kontrolę źródła?

Czy potrafisz zrozumieć, co się od tego zmieniło?

Jeśli tak, to możesz być w stanie odwzorować to na zmiany biznesowe, czy to nowe funkcje, czy poprawki błędów.

Czy można wskrzesić starą skrzynkę programistów? (nie jestem pewien, czy jest to uzasadnione obawami dotyczącymi prywatności). Przebywanie włokiem może być źródłem wielu informacji.

Najpierw pierwsze. Gdzie przechowujesz swoją dokumentację? Jeśli jeszcze tego nie zrobiłeś, załóż wiki. Sam wolę dokuwiki , a nawet masz gotową wersję vm , jeśli masz na to ochotę.

Zapewnia to kilka ważnych funkcji:

• Dokumenty są dostępne w dowolnym miejscu w sieci LAN (instalacja na nowym komputerze ...)
• Wszystkie dokumenty są w jednym miejscu
• Wszystkie dokumenty można przeszukiwać
• Możesz współpracować (nowy współpracownik, użytkownicy oprogramowania)

Teraz, jeśli twoja dokumentacja jest w formie papierowej, życzę ci wszystkiego najlepszego. Jeśli masz dokumenty Word, zbuduj skrypt importu .

Wreszcie, po prostu użyj tego . Ilekroć musisz coś zainstalować, umieść notatki na wiki. Jeśli trafisz na skrzynkę brzegową, umieść ją na wiki. Tutaj może zabłysnąć współpraca, ponieważ zachęcasz innych ludzi do wykonania pracy za Ciebie.

Przechodząc do bardziej szczegółowej dokumentacji, jeśli potrzebujesz pracować ze źródłem dla różnych projektów, upewnij się, że masz skonfigurowane odpowiednie środowisko programistyczne ! Aby uzyskać listę kontrolną rzeczy, które powinieneś mieć:

• Kontrola wersji ( git , merkurial , fossil )
• Śledzenie błędów ( trac , modliszka , redmine , skamielina )
• Kompilacja systemu ( narzędzia automatyczne , scons , buildbot )
• Kontrola projektu ( zaćmienie , określona struktura katalogów, wtyczka edytora )
• Dokumentacja źródłowa (README, TODO, INSTALL, komentarze źródłowe)

Wreszcie, ponieważ dokumentacja może być nudna, uczyń ją grą. Daj sobie „punkty” za każdy element na liście kontrolnej, okresowo sprawdzając „wynik”. To dobry sposób, aby zobaczyć, co osiągnąłeś i jak dobrze. Wyznacza także, gdzie musisz iść dalej.

Spójrz na to jako okazję do nauczenia się wielu rzeczy na temat konfigurowania odpowiedniego środowiska programistycznego i nie bój się próbować różnych rzeczy i iść dalej. Znajdź coś, co Ci się podoba i migruj środowisko, aby było lepiej . Podejdź do tego jako projektu, w którym chcesz zbudować najlepsze rozwiązanie.

Edytować:

Zgodnie z komentarzem platformy poniżej, kolejną przydatną rzeczą do zrobienia jest tworzenie diagramów kodu źródłowego. Freecode ma wiele rzeczy , aw tym artykule wymieniono niektóre popularne języki.

Najlepsze, co możesz zrobić, to udokumentować wszystko, co wiesz, i poprosić firmę o udokumentowanie czegokolwiek, co wiedzą także inni. Proponuję scentralizować dokumentację na wiki lub czymś podobnym, aby każdy miał dostęp do najbardziej aktualnej dokumentacji.

Nie możesz udokumentować czegoś, czego nie znasz, więc albo próbujesz dowiedzieć się, dlaczego coś zostało zrobione, albo po prostu pozostawiasz to nieudokumentowane. Właśnie dlatego firma musi dokładać starań, aby dokumentować rzeczy, podczas gdy ci, którzy wiedzą, są tam nadal zatrudnieni.

Jeśli próbujesz udokumentować dowolny kod, którego nie rozumiesz, sugeruję napisanie testów jednostkowych w celu przetestowania funkcjonalności. W ten sposób lepiej zrozumiesz, co robi kod, a same testy mogą służyć jako dokumentacja.

Powodzenia!

Kiedy próbuję udokumentować coś, co zrobił ktoś inny, kto nie jest już związany z projektem lub firmą, zawsze zaczynam podejście: To jest czarna skrzynka dla wszystkich, w tym dla mnie, dopóki nie będę musiał czegoś zmienić lub wyjaśnić komuś innemu.

Powodem, dla którego projekt ten ma kształt dokumentacji, w której go znalazłeś, jest to, że dokumentacja jakiejkolwiek pracy jest nieco drugorzędna w stosunku do uruchomienia. Więc udokumentuj, co zmieniasz, a jeśli zorientowałeś się, jakie jest konkretne pole w bazie danych i jaki konkretny blok kodu, jeśli nie dla nikogo innego, tylko dla ciebie.

Możesz napisać automatyczne testy eksploracyjne. Mają one kilka zalet:

• Dowiadujesz się, jak działa system, kiedy je piszesz

• Służą one jako dokumentacja wykonywalna na później

• Jeśli uruchamiasz je regularnie, a nawet w sposób ciągły, stanowią one dobrą sieć bezpieczeństwa do wykrywania, gdy zmiany coś psują lub kiedy trzeba je zaktualizować

Nie wiem jednak, czy możliwe jest napisanie tego rodzaju testów w twoim konkretnym środowisku.