Igor Janicki

Igor Janicki Software maker.
Java, Perl ...

Temat: dokumentacja projektu


Obrazek


Czy znacie jakieś standardy lub wzorce profesjonalnej dokumentacji technicznej projektu. ?

ongiś zagraniczny zleceniodawca/pracodawca miał i standardy i wymagania. morze czasu upłynęło. jak jest teraz ?

konto usunięte

Temat: dokumentacja projektu

Igor J.:

Obrazek


Czy znacie jakieś standardy lub wzorce profesjonalnej dokumentacji technicznej projektu. ?

ongiś zagraniczny zleceniodawca/pracodawca miał i standardy i wymagania. morze czasu upłynęło. jak jest teraz ?

Z punktu widzenia programisty... dokumentacja jest od tego, żeby opisać z jakimi problemami dany element systemu sobie radzi, jakie rozwiązania były brane pod uwagę, co zostało wybrane do implementacji i dlaczego. Jak wygląda implementacja - każdy może sobie sprawdzić. W praktyce dokumentację pisze się po i to jest problem.

No, oczywiście nie tylko programista używa systemu. Ci inni mają inne potrzeby - wdrożeniowiec, administrator, czy użytkownik raczej będą chcieli czegoś innego...

Czy jest robiona w JDocach, czy trzymana na wiki / osobno - wielkiej różnicy nie ma. O ile jest dobrze określona metodyka jej prowadzenia. W sensie - każde rozwiązanie ma plusy, ma też minusy - ważne, żeby każdy wiedział po co to jest, jak się tym posługiwać, na co można liczyć i takie tam.

A jak jest teraz, jakie są zalecenia? - w google proszę wpisać "system architecture document example" - na stack overflow jest parę wątków, IBM też coś spłodził...
Maciej G.

Maciej G. Projektant /
Programista, Famor
S.A.

Temat: dokumentacja projektu

UML, Doxygen (też może generować diagramy klas w UML, najlepiej wystawić wygenerowaną dokumentacje w formacie HTML na jakimś serwerze WWW) , Wiki - i masz wszystko co potrzebne programistom (konserwującym, rozwijającym projekt).

Dla userów trzeba wyrzeźbić dokumentacje obsługi aplikacji/poradnik jak radzić sobie z często napotykanymi w systemie problemami.

Pozdrawiam.
Marcin Mackiewicz

Marcin Mackiewicz Programista JAVA, RS
Adware Polska

Temat: dokumentacja projektu

Komplet dokumentacji dla projektów u mnie nie zawsze ale przy ważniejszych projektach składa się:
1. Założenia merytoryczne, analiza opłacalności oraz potrzeby. Wstępny zarys funkcjonalności (opracowuje biznes + analityk).
2. Projekt funkcjonalny, techniczny. Zawiera merytoryczny opis funkcjonalności do wykonania (opracowuje biznes + analityk) oraz techniczny opis funkcjonalności np. przypadki użycia, przepływ, informacje o przechowywanych danych w db (opracowuje analityk + ewentualnie informatyk programista).
3. Dokumentacja techniczna. Zawiera informacje dotyczące kodu i zaimplementowanych funkcjonalności. Dokumentacja tworzona w popularnym dla danej technologii doku (np. javadoc, phpdoc). Tworzona przez programistę i z reguły generowana do postaci HTML.
4. Instrukcja instalacji gotowego narzędzia (powinien tworzyć analityk albo wdrożeniowiec ale u nas kończy się na testerze albo programiście ...).
5. Instrukcja użytkownika (powinien tworzyć analityk albo wdrożeniowiec ale jest tak jak w poprzednim punkcie).

Dodatkowo jeszcze może być generowany changelog z komentarzy przy aktualizacji SVN lub innego popularnego repozytorium i udostępniany wraz z wyprodukowaną aplikacją.

Ostatni projekt był odświeżeniem oprogramowania napisanego z 6-7 lat temu i tu zrobiłem instrukcję użytkownika w postaci zestawu screencast'ów (ok 1h nagrań). Muszę powiedzieć, że wśród użytkowników końcowych przyjęło się lepiej niż instrukcja papierowa która również została zaktualizowana.
Maciej G.

Maciej G. Projektant /
Programista, Famor
S.A.

Temat: dokumentacja projektu


Ostatni projekt był odświeżeniem oprogramowania napisanego z 6-7 lat temu i tu zrobiłem instrukcję użytkownika w postaci zestawu screencast'ów (ok 1h nagrań). Muszę powiedzieć, że wśród użytkowników końcowych przyjęło się lepiej niż instrukcja papierowa która również została zaktualizowana.

Bardzo dobry pomysł - popieram czterema kończynami. Ja też najbardziej cenię tutoriale na youtube.com z pracy z konkretnym środowiskiem programistycznym/IDE.

Pozdrawiam.Ten post został edytowany przez Autora dnia 03.04.15 o godzinie 20:59
Igor Janicki

Igor Janicki Software maker.
Java, Perl ...

Temat: dokumentacja projektu

a może są jakieś standardy i narzędzia do bug-book


Obrazek


najszczęśliwiej było by jeśli zintegrowane z Redmine.
Maciej G.

Maciej G. Projektant /
Programista, Famor
S.A.

Temat: dokumentacja projektu

Hej Igor,

chodzi Ci o sam system do "bug tracking'u", czy łącznie z systemem zarządzania projektami według metodyki "Agile-Scrum" (np. wymieniony "Redmine" lub "Jira"). "Redmine" to wielka kobyła (ma sens do zarządzania projektami opartymi o Agile-Scrum), jeśli chodzi o sam "bug tracker" to wolałbym coś lżejszego np. "Bugzilla" (jeśli nie potrzebujesz opcji zarządzania projektami i skomplikowanego "ticketowania". W "Redmine" jest wewnętrzny moduł zwany "Issue tracking System", ktory służy do tego celu. Wygląd tego modułu możesz zobaczyć pod tym linkiem:


Obrazek


Pozdrawiam.Ten post został edytowany przez Autora dnia 07.04.15 o godzinie 15:37
Igor Janicki

Igor Janicki Software maker.
Java, Perl ...

Temat: dokumentacja projektu

dziękuję :)

konto usunięte

Temat: dokumentacja projektu

Jeżeli na szybko potrzebujesz zestawu templateów + informacji na jakim etapie projektu warto ich użyć (nie tylko dla dokumentacji technicznej), to tu jest taki "open sourceowy" zestaw:
http://readyset.tigris.org/

Od jakiegoś czasu nie aktualizowany, ale przy starcie "od zera" (lub prawie "od zera") pozwala szybciej usystematyzować i zorganizować dokumentację.

pzdr,
Maciek

Następna dyskusja:

poszukuje wykonawcy projekt...




Wyślij zaproszenie do