Dokumentowanie projektu

Wprowadzenie

Artykuł Architektura kodu aplikacji jako pierwszy etap tworzenia oprogramowania napisany w 2017 roku, kończyłem słowami:

Nie chodzi więc o to by podzielić oprogramowanie na “składowe, które łączą w sobie możliwość przechowywania danych oraz wykonywania operacji”. Chodzi o to by mechanizm, o dowiedzionej poprawności, zaimplementować w określonej wybranej technologii.

https://it-consulting.pl/2017/07/15/architektura-kodu-aplikacji-jako-pierwszy-etap-tworzenia-oprogramowania/

Dokumentowanie i dokumentacja w projektach inżynierii oprogramowania to temat wielu i sporów i nieporozumień. Jednak kluczowymi błędami są najczęściej:

  1. teza, że dokumentację tworzymy po zakończeniu prac,
  2. teza, że jest to “jedna dokumentacja”.

ad.1. Niestety to najgorsza forma, bo etap rozwiązywania problemu realizowany jest wprost z użyciem kodu (code first), czyli najkosztowniejszą metodą. Praktyka pokazuje, że zwinne projekty “code-first” owocują nawet 10krotnie niższa efektywnością.

ad.2. Jest to założenie, że nie ma granicy między środowiskiem aplikacji a aplikacją.

Obie formy są możliwe do realizacji, pytanie czy nie można inaczej i lepiej? Logikę się projektuje przed kodowaniem, infrastrukturę się dokumentuje po jej uruchomieniu.

Aplikacja i jej środowisko to dwa różne projekty

Od 2003 roku (publikacja opisu tak zwanej architektury heksagonalnej):

źr.: https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together/

Powyższy diagram (dość często cytowany w literaturze, ) pokazuje ideę tego wzorca architektonicznego: separujemy realizację wymagań funkcjonalnych (aplikacja, obszar objęty czerwoną granicą) od środowiska w jakim ona sie wykonuje (obszar poza czerwona granicą). Dokładnie tak samo jak np. kod aplikacji Edytor Tekstu od kodu MS Windows. Są to zupełnie dwa różne produkty, a jedyne co je łączy to to to że, edytor tekstu korzysta z usług systemu operacyjnego przez jego API (porty). Identycznie tworzymy każde inne oprogramowanie: aplikacja osobno, środowisko osobno.

Dokumentacja czyli co to jest i ile zajmuje czasu

Każdy projekt inżynierski ma kilka faz, są to: określenie problemu i wskazanie rozwiązania, określenie wymagań wobec rozwiązania, zaprojektowanie rozwiązania, implementacja i wdrożenie rozwiązania.

Tak więc mamy:

  1. Dokumentację działania organizacji czyli udokumentowany jej biznesowy model działania. W nomenklaturze OMG jest to Computation Independent Model:
    • mapy procesów biznesowych (BPMN),
    • słownik pojęci i reguły biznesowe (SBVR)
    • procedury (RACI, CRUD, listy kontrolne)
    • szablony dokumentów (diagram struktur złożonych UML, inne formy graficzne)
  2. Specyfikacja wymagań, forma zależna od preferencji:
    • wymagania funkcjonalne i poza-funkcjonalne,
    • user story,
    • inne.
  3. Dokumentacja-projekt HLD, tu “z lotu ptaka” pokazujemy projekt realizacji funkcjonalności i strategię utrzymania i rozwoju aplikacji (notacja UML/SysML):
    • Lista usług systemu (przypadki użycia UML)
    • Architektura HLD (diagram komponentów UML)
    • Specyfikacje i scenariusze przypadków użycia na poziomie HLD (diagramy sekwencji UML, diagramy aktywności UML)
  4. Dokumentacja-projekt realizacji wymagań pozafunkcjonalnych czyli platformy systemowej i środowiska aplikacji (notacja UML/SysML, architektura C4, inne formy dokumentacji dostarczonej prze producenta platformy).
  5. Dokumentacja-projekt LLD, realizacji określonych komponentów wskazanych na modelu HLD:
    • Architektura LLD (diagram klas UML),
    • Specyfikacje i scenariusze operacji komponentu na poziomie LLD (diagramy sekwencji UML, diagramy aktywności UML)
  6. Implementacja komponentu

Praktyka autora tego tekstu i wielu innych autorów podobnych publikacji , pokazuje, że:

  • etap analizy biznesowej i spisanie wymagań to ok. 3 miesiące,
  • opracowanie architektury HLD to maksymalnie ok. 1 tydzień,
  • każdy komponent LLD to nie raz nawet tylko kilka godzin rysowania w UML,
  • implementacja tych kolejnych komponentów w zbudowanym już środowisku, to dni a rzadziej tygodnie.

Etapy te zostały ujęte w tak zwany V-model , z perspektywy projektów inżynierii oprogramowania, zobrazowany poniżej:

V-Model is also referred to as the Verification and Validation Model. In this, each phase of SDLC must complete before the next phase starts. It follows a sequential design process the same as the waterfall model. The testing of the device is planned in parallel with a corresponding stage of development. (źr.: V-model (Software Engineering) – javatpoint).

Analityk-projektant realizuje elementy analizy i projektowania, deweloper to punkt 4. oraz kolejne realizacje pkt. 6. Projekt ma trzy ramowe etapy:

  1. Analiza biznesowa: analityk-projektant.
  2. Specyfikacja Wymagań: analityk-projektant;
  3. Projektowanie rozwiązania i iteracyjno-przyrostowe wytwarzanie go: w petli SDLC analityk-projektant + deweloper .

Jeżeli projekt jest komponentowy, wtedy V-model przybiera postać jak poniżej:

(na podstawie )

Tak więc z perspektywy dewelopera, użyteczne oprogramowanie powstaje już po niecałych 2 tygodniach. To wynik niemalże nie do osiągniecia przy pracy bez analiz i projektu od razy w kodzie na bazie user story. Ważne jest także to, że zyskujemy tak dokumentację zmian w całym cyklu życia projektu (ADR, ang. Architecture Decision Records, ) co jest bardzo ważne z perspektywy zarządzania zmianą.

Podsumowanie

Metody zwane agile, spopularyzowały podejście zwane code-first. Niestety czas pokazał, że w dłuższej perspektywie są najmniej efektywne:

Badanie wykazało 268% wyższy wskaźnik niepowodzeń w projektach oprogramowania Agile.

https://www.theregister.com/2024/06/05/agile_failure_rates/

Efektywność uzyskujemy przemyślaną architekturą i potem jej sprawną implementacją (np. językami skryptowymi). Doświadczony projektant, w rozwiązywaniu problemów dziedzinowych, jest nawet dziesięciokrotnie efektywniejszy niż koder pracujący od razu z kodem z tradycyjnymi frameworkami takimi jak JavaEE/Spring czy bardzo podobnym .NET Framework.

W kwestii same organizacji dokumentacji co do zasady: dokumentujemy od ogółu do szczegółu, oraz zawsze osobno logikę i osobno infrastrukturę.

Bardzo ważne: logikę się projektuje przed kodowaniem, infrastrukturę się dokumentuje po jej uruchomieniu .

Prowadzę warsztaty dla zespołów analityków, projektantów i deweloperów, na których prezentuję, omawiam i wyjaśniam opisane wyżej i dobrze znane na świecie metody projektowania i dokumentowania (wykup warsztaty dla zespołu albo umów sie na indywidualne konsultacje). Od niedawna oferuje "gotowce" jako wzory i przykłady w Sklepiku.

Źródła

-Brandl, -D. (2002). Business to manufacturing (B2M) collaboration between business and manufacturing using ISA-95. Revue de l’Electricité et de l’Electronique, (08), 46. https://doi.org/10.3845/ree.2002.087
A. H. Maslow. (1943). A Theory of Human Motivation. http://psychclassics.yorku.ca/Maslow/motivation.htm
Aalst, W. (2010). Business Process Simulation Revisited (Vol. 63).
Abdelhak Khalil, Mustapha Belaissaoui, & Foudad Toufik. (2023). A Data Placement Strategy for Distributed Document-oriented Data Warehouse. IANG International Journal of Computer Science, 50(4). https://www.iaeng.org/IJCS/issues_v50/issue_4/IJCS_50_4_44.pdf
Abdelhedi, F., Brahim, A., Ferhat, R., & Zurfluh, G. (2020). Discovering of a Conceptual Model from a NoSQL Database: Proceedings of the 22nd International Conference on Enterprise Information Systems, 61–72. https://doi.org/10.5220/0009796100610072
Abdelhedi, F., Jemmali, R., & Zurfluh, G. (2022). Relational Databases Ingestion into a NoSQL Data Warehouse. 6.
Abdelhedi, F., Rajhi, H., & Zurfluh, G. (2022). Extraction Process of the Logical Schema of a Document-oriented NoSQL Database: Proceedings of the 10th International Conference on Model-Driven Engineering and Software Development, 61–71. https://doi.org/10.5220/0010899000003119
Abetti, P. A., Cuthbertson, W. J., & Williams, S. B. (1958). Philosophy of applying digital computers to the design of electric apparatus. Transactions of the American Institute of Electrical Engineers, Part I: Communication and Electronics, 77(3), 367–379. https://doi.org/10.1109/TCE.1958.6372814
Abid, H., Philippe, P., Noterman, D., Campagne, J.-P., & Ben Amar, C. (2014). SysML approach for the integration of mechatronics system within PLM systems. International Journal of Computer Integrated Manufacturing, 28, 972–987. https://doi.org/10.1080/0951192X.2014.941938
Abrial, J.-R., Butler, M., Hallerstede, S., Hoang, T. S., Mehta, F., & Voisin, L. (2010). Rodin: an open toolset for modelling and reasoning in Event-B. International Journal on Software Tools for Technology Transfer, 12(6), 447–466. https://doi.org/10.1007/s10009-010-0145-y
Achouch, M., Dimitrova, M., Ziane, K., Sattarpanah Karganroudi, S., Dhouib, R., Ibrahim, H., & Adda, M. (2022). On Predictive Maintenance in Industry 4.0: Overview, Models, and Challenges. Applied Sciences, 12(16), 8081. https://doi.org/10.3390/app12168081
Ackoff, R. L. (1999). Ackoff’s best: his classic writings on management. Wiley.
Ackoff, R. L. (1999). From data to wisdom. In Ackoff’s Best (pp. 170–172). John Wiley & Sons.
Ackoff, R. L. (1967). Management misinformation systems. Management Science, 14(4), B-147.
Ackoff, R. L., Magidson, J., & Addison, H. J. (2006). Idealized design: creating an organization’s future. Wharton School Pub.
Ackoff, R. L., Magidson, J., Addison, H. J., & Ehrlich, A. (2007). Projektowanie ideału: kształtowanie przyszłości organizacji. Wyższa Szkoła Przedsiębiorczości i Zarządzania im. Leona Koźmińskiego : Wydawnictwa Akademickie i Profesjonalne. https://repozytorium.kozminski.edu.pl/pl/pub/3442
Adair, C. B., & Murray, B. A. (2001). Radykalna reorganizacja firmy. WNT.
Adamczyk, J. (2017). Nowe formy szczególne czynności prawnych w Kodeksie cywilnym–dokumentowa oraz elektroniczna–a obowiązywanie rozporządzenia eIDAS. Prawo Mediów Elektronicznych,(4). https://www.repozytorium.uni.wroc.pl/Content/123581
Adamo, G., Ghidini, C., & Di Francescomarino, C. (2021). What is a process model composed of?: A systematic literature review of meta-models in BPM. Software and Systems Modeling. https://doi.org/10.1007/s10270-020-00847-w
Adams, M., Hense, A. V., & Hofstede, A. H. M. ter. (2021). Extensible ontology-based views for business process models. Knowledge and Information Systems, 63(10), 2763–2789. https://doi.org/10.1007/s10115-021-01604-1
Agaronian, A., Freyer, C. W. S., Bierbooms, C. G., Hoeijmakers, T. P. H., Jansen, T., Kafoe, T., Makantasis, I., Mankevic, K., Sinx, R. D., & Smits, I. M. (2019). Software Requirements Document. 133.
Agarwal, S., Pape, L., Dagli, C. H., Kilicay-Ergin, N., Enke, D., Gosavi, A., Qin, R., Konur, D., Wang, R., & Gottapu, R. D. (2015). Flexible and Intelligent Learning Architectures for SoS (FILA-SoS): Architectural Evolution in Systems-of-Systems. Procedia Computer Science, 44. https://doi.org/10.1016/j.procs.2015.03.005
Agata Kukwa. (2020, wrzesie). Dlaczego maski nie ochronią Cię przed infekcją wirusową? – badania.net. https://www.badania.net/dlaczego-maski-nie-ochronia-cie-przed-infekcja-wirusowa/
Aggarwal, I. (2021). HIGH PERFORMANCE DOCUMENT STORE IMPLEMENTATION IN RUST. 38.
Aggoune, A., & Namoune, M. S. (2022). Metadata-driven Data Migration from Object-relational Database to NoSQL Document-oriented Database. Computer Science, 23(4). https://doi.org/10.7494/csci.2022.23.4.4375
Agnieszka Kamińska, Marcin Kotarba, Janusz Stańczak, Andrzej Zajkowski, & Janusz Zawiła-Niedźwiecki. (2022). Projektowanie strategii informatyzacji organizacji (Vol. 1–1). Politechnika Warszawska, Wydział Zarządzania. https://www.researchgate.net/publication/357096265_Projektowanie_strategii_informatyzacji_organizacji
Ahmad, S. I., Rana, T., & Maqbool, A. (2021). A Model-Driven Framework for the Development of MVC-Based (Web) Application. Arabian Journal for Science and Engineering. https://doi.org/10.1007/s13369-021-06087-4
Ahmad, A., Waseem, M., Liang, P., Fehmideh, M., Khan, A. A., Reichelt, D. G., & Mikkonen, T. (2023). Engineering Software Systems for Quantum Computing as a Service: A Mapping Study (No. arXiv:2303.14713). arXiv. http://arxiv.org/abs/2303.14713
Ahmed M. (2010). Requirements Analysis through Viewpoints Oriented Requirements Model (VORD). International Journal of Advanced Computer Science and Applications, 1(5). https://doi.org/10.14569/IJACSA.2010.010502
Aicher, T., Fottner, J., & Vogel-Heuser, B. (2022). A model-driven engineering design process for the development of control software for Intralogistics Systems. At - Automatisierungstechnik, 70(2), 164–180. https://doi.org/10.1515/auto-2021-0068
AIIM. (2022). AIIM 2022 State of the Intelligent Information Management Industry. 39.
Ain el hayat, S. (2020). Modeling and Transformation from Temporal Object Relational Database into Mongodb: Rules. Advances in Science, Technology and Engineering Systems Journal, 5, 618–625. https://doi.org/10.25046/aj050473
Ajdukiewicz, K. (2008). Główne zasady logiki i metodologii: wykłady z roku 1949. Filozofia Nauki 16/1, 117–157. http://bazhum.muzhp.pl/media//files/Filozofia_Nauki/Filozofia_Nauki-r2008-t16-n1/Filozofia_Nauki-r2008-t16-n1-s117-157/Filozofia_Nauki-r2008-t16-n1-s117-157.pdf
Akademia Leona Koźminskiego. (2023, December 19). Zwinne zarzadzanie projektami – Agile w pigułce. Akademia Leona Koźminskiego Warszawa. https://www.kozminski.edu.pl/pl/review/zwinne-zarzadzanie-projektami-agile-w-pigulce
Akatkin, Y. M., Bich, M. G., Yasinovskaya, E. D., & Shilin, A. V. (2021). THE TECHNOLOGY AND TOOLS FOR THE BUILDING OF INFORMATION EXCHANGE PACKAGE BASED ON SEMANTIC DOMAIN MODEL. 6.
Akehurst, D. H. (2004). Computer Science at Kent. Citeseer.
Akundi, A., Lopez, V., & Tseng, B. (2021). Identifying the Thematic Trends of Model Based Systems Engineering in Manufacturing and Production Engineering Domains. https://doi.org/10.1109/SysCon48628.2021.9447071
Al-Fedaghi, S. (2020). Conceptual Modeling of Time for Computational Ontologies. 14.
Al-Fedaghi, S. (n.d.). Preconceptual Modeling in Software Engineering: Metaphysics of Diagrammatic Representations.
Al-Fedaghi, S., & AlSaraf, M. (2020). High-Level Description of Robot Architecture. International Journal of Advanced Computer Science and Applications, 11(10), 10.
Aladdin, A., Bakir, Y., & Saeed, S. (2018). The Effects to Trend the Suitable OS Platform. JOURNAL OF ADVANCES IN NATURAL SCIENCES, 5, 342–351. https://doi.org/10.24297/jns.v5i1.7528
Alain Strowel. (2020). Private Copying Levies Do Not Apply in the Case of Streaming. Bitkom e.V. https://www.bitkom.org/sites/default/files/2020-04/expert-opinion_streaming-and-private-copying-levies_strowel.pdf
Alan Grosskurth, & Michael W. Godfreyz. (2006). A reference architecture for web browsers. Journal of Software Maintenance and Evolution: Research and Practice.
Alassaf, N., & Clayton, M. (2021). The Use of Diagrammatic Reasoning to Aid Conceptual Design in Building Information Modeling (BIM). Building Information Modelling, Volume 2, 10.
Alavi, M., & Leidner, D. E. (2001). Review: Knowledge Management and Knowledge Management Systems: Conceptual Foundations and Research Issues. MIS Quarterly, 25(1), 107. https://doi.org/10.2307/3250961
Albarello, N., Welcomme, J.-B., & Reyterou, C. (2012, June). A formal design synthesis and optimization method for systems architectures. 9th International Conference on Modeling, Optimization & SIMulation. https://hal.archives-ouvertes.fr/hal-00728577
Albers, A., Bursac, N., Scherer, H., Birk, C., Powelske, J., & Muschik, S. (2019). Model-based systems engineering in modular design. Design Science, 5, e17. https://doi.org/10.1017/dsj.2019.15
Alencar, F. (2000). Closing the GAP between organizational requirements and object oriented modeling. Journal of the Brazilian Computer Society. https://www.academia.edu/83364710/Closing_the_GAP_between_organizational_requirements_and_object_oriented_modeling
Alexander, J. (2012). Experimental philosophy: an introduction. Polity.
Alexander, A., Walker, H., & Delabre, I. (2022). A Decision Theory Perspective on Wicked Problems, SDGs and Stakeholders: The Case of Deforestation. Journal of Business Ethics. https://doi.org/10.1007/s10551-022-05198-8

Jarosław Żeliński

Jarosław Żeliński: autor, badacz i praktyk analizy systemowej organizacji: Od roku 1991 roku, nieprzerwanie, realizuje projekty z zakresu analiz i projektowania systemów, dla urzędów, firm i organizacji. Od 1998 roku prowadzi samodzielne studia i prace badawcze z obszaru analizy systemowej i modelowania (modele jako przedmiot badań: ORCID). Od 2005 roku, jako nieetatowy wykładowca akademicki, prowadzi wykłady i laboratoria (ontologie i modelowanie systemów informacyjnych, aktualnie w Wyższej Szkole Informatyki Stosowanej i Zarządzania pod auspicjami Polskiej Akademii Nauk w Warszawie.) Oświadczenia: moje badania i publikacje nie mają finansowania z zewnątrz, jako ich autor deklaruję brak konfliktu interesów. Prawa autorskie: Zgodnie z art. 25 ust. 1 pkt. 1) lit. b) ustawy o prawie autorskim i prawach pokrewnych zastrzegam, że dalsze rozpowszechnianie artykułów publikowanych w niniejszym serwisie jest zabronione bez indywidualnej zgody autora (patrz Polityki Strony).

Dodaj komentarz

Witryna wykorzystuje Akismet, aby ograniczyć spam. Dowiedz się więcej jak przetwarzane są dane komentarzy.