Dokumentacja wersji oprogramowania urządzenia – identyfikatory, zmiany i zgodność z modelem

W urządzeniu elektronicznym oprogramowanie może sterować pracą układów, odczytywać sygnały z czujników i realizować funkcje przewidziane przez producenta. Informacja o jego wersji pomaga ustalić, jaki zestaw instrukcji działał w danym egzemplarzu albo wariancie modelu. Sama nazwa urządzenia nie wystarcza do takiej identyfikacji, ponieważ pod jedną nazwą mogą występować różne rewizje sprzętu i oprogramowania.

Dokumentacja wersji porządkuje identyfikatory, daty, zakres zmian oraz relacje między oprogramowaniem a modelem. Jej zapisy mają znaczenie przy odczytywaniu dokumentacji technicznej, instrukcji obsługi i wyników badań. Wartość wersji należy odczytywać z oznaczeń producenta, karty produktu lub właściwego dokumentu urządzenia; nie należy jej wyprowadzać wyłącznie z wyglądu obudowy ani z nazwy handlowej.

Rola identyfikatora wersji

Identyfikator wersji jest oznaczeniem przypisanym do określonego wydania oprogramowania. Może mieć postać numeru, ciągu znaków albo oznaczenia łączącego kilka pól. Producent określa jego format, dlatego ten sam zapis liczbowy może w różnych urządzeniach oznaczać odmienne rzeczy. W dokumentacji powinno być jasno wskazane, czy identyfikator odnosi się do całego programu, konkretnego modułu, czy pakietu obejmującego kilka składników.

Wersja pozwala odróżnić zestawy instrukcji, lecz sama nie opisuje ich funkcji ani zakresu zmian. Numer wyższy nie musi oznaczać większej liczby funkcji, a kolejna litera nie zawsze wskazuje nowsze wydanie. Znaczenie oznaczenia wynika z zasad wersjonowania przyjętych przez producenta. W razie braku opisu tej konwencji należy traktować identyfikator jako etykietę, a nie samodzielny opis techniczny.

W zapisie identyfikatora należy zachować wszystkie człony, separatory, prefiksy i zera wiodące, jeśli występują. Skrócenie numeru może utrudnić odróżnienie dwóch wydań lub doprowadzić do pomylenia wersji programu z oznaczeniem partii produkcyjnej. Dokumentacja powinna też wskazywać źródło odczytu: na przykład ekran informacyjny urządzenia, etykietę, plik producenta albo kartę produktu.

Definicje podstawowych pojęć

• Wersja oprogramowania – oznaczenie wydania programu lub jego składnika, zdefiniowane według reguł producenta.
• Rewizja sprzętu – oznaczenie zmiany konstrukcyjnej lub konfiguracji podzespołów urządzenia; nie jest tożsama z wersją programu.
• Identyfikator modelu – oznaczenie wariantu urządzenia, do którego producent przypisuje określone parametry i dokumenty.
• Wersjonowanie – zasady nadawania oznaczeń kolejnym wydaniom i opisywania relacji między nimi.
• Informacja o wydaniu – dokument opisujący identyfikator, zakres zmian, ograniczenia i warunki stosowania danego wydania.
• Zgodność – potwierdzone przez dokumentację przypisanie wersji do określonego modelu lub wariantu, w ustalonym zakresie.

Terminy te bywają stosowane niejednolicie, dlatego dokument producenta powinien określać, jak rozumie każde pole. „Rewizja”, „wersja” i „seria” mogą występować obok siebie, ale opisują różne cechy. Rewizja może dotyczyć płytki elektronicznej, wersja – programu sterującego, a seria – partii produkcyjnej. Zastąpienie jednego terminu drugim bez wyjaśnienia zaciera informację o tym, co faktycznie uległo zmianie.

Również określenia „aktualizacja” i „nowa wersja” nie muszą być równoważne. Aktualizacja jest działaniem polegającym na zmianie oprogramowania w urządzeniu lub przygotowaniu go do takiej zmiany. Nowa wersja to wydanie oznaczone przez producenta. Dokumentacja powinna więc oddzielać identyfikator wydania od informacji, czy, kiedy i w jaki sposób można je zastosować do danego egzemplarza.

Budowa zapisu wersji

Oznaczenie może zawierać kilka części, na przykład główny numer wydania, numer poprawki i sufiks opisujący wariant. Nie należy jednak zakładać, że zapis ma powszechnie przyjętą strukturę. Producent może używać własnego schematu, a podobne ciągi znaków mogą pełnić różne role. Objaśnienie pól powinno znaleźć się w dokumentacji wersjonowania lub w informacji o wydaniu.

Gdy zapis zawiera oddzielne oznaczenia dla różnych modułów, każde z nich należy przypisać do odpowiedniego elementu. Urządzenie może mieć oprogramowanie sterujące, moduł komunikacyjny i interfejs, których wydania zmieniają się niezależnie. Podanie tylko jednego numeru w takim przypadku może być niewystarczające do odtworzenia konfiguracji. Dokument powinien wyjaśniać, czy przedstawiona wersja jest nadrzędna, zbiorcza, czy dotyczy jednego składnika.

W dokumentach warto zachować oryginalny zapis producenta, a obok niego podać jego objaśnienie w języku polskim. Nie należy samodzielnie przekształcać liter na liczby ani usuwać znaków, które wydają się technicznie nieistotne. Przy porównywaniu dwóch zapisów istotne są zarówno ich pełna postać, jak i informacja o źródle. Pozwala to odróżnić rzeczywistą zmianę wydania od błędu przepisywania.

Identyfikacja modelu i wariantu

Model jest punktem odniesienia dla dokumentacji, ale nazwa modelu może obejmować kilka wariantów. Różnice mogą dotyczyć podzespołów, obszaru przeznaczenia, funkcji albo sposobu konfiguracji. Jeżeli producent rozróżnia warianty osobnymi kodami, należy zachować je razem z identyfikatorem modelu. Sama nazwa na obudowie nie zawsze ujawnia wszystkie różnice, dlatego istotne jest odczytanie pełnego oznaczenia z etykiety lub dokumentu producenta.

Powiązanie wersji oprogramowania z modelem powinno określać, które wydania mają zastosowanie do którego wariantu. Może to być wykaz kodów urządzeń, zakres rewizji sprzętu albo odniesienie do dokumentu konfiguracji. Gdy takiego przypisania brakuje, nie należy zakładać, że plik przeznaczony dla podobnie nazwanego modelu jest zgodny. Podobieństwo nazwy nie zastępuje potwierdzenia producenta.

W zapisie identyfikacyjnym przydatne są pola: nazwa modelu, kod wariantu, rewizja sprzętu, wersja oprogramowania i źródło informacji. Nie każde urządzenie udostępnia wszystkie te dane na ekranie lub etykiecie. Brak danego pola należy opisać jako brak informacji w użytym źródle, a nie uzupełniać domysłem. Takie podejście pozwala odróżnić dane od interpretacji i ogranicza ryzyko przypisania dokumentu do niewłaściwego urządzenia.

Odczyt oznaczeń z urządzenia i opakowania

Oznaczenia mogą znajdować się na tabliczce znamionowej, etykiecie opakowania, w menu urządzenia albo w dokumentacji dołączonej przez producenta. Miejsce ich umieszczenia zależy od konstrukcji i rodzaju produktu. Należy zapisać dokładną nazwę pola, jego wartość oraz miejsce odczytu. Jeżeli etykieta zawiera kod modelu, numer seryjny i oznaczenie partii, nie należy uznawać każdego z nich za numer wersji oprogramowania.

Na karcie produktu mogą być przedstawione parametry sprzętowe i identyfikatory modelu bez informacji o zainstalowanym wydaniu programu. Karta opisuje wtedy rodzinę produktu lub wariant katalogowy, a niekoniecznie konkretny egzemplarz. Rozróżnienie jest istotne: numer seryjny wiąże się zwykle z pojedynczym urządzeniem, natomiast oznaczenie modelu może obejmować wiele egzemplarzy. Zakres informacji karty należy odczytać z jej opisu.

Gdy dostępne są różne źródła, należy zachować ich pochodzenie i datę odczytu. Etykieta może podawać wersję początkową, natomiast ekran urządzenia – wersję aktualnie zainstalowaną. Są to informacje dotyczące różnych momentów. Zapis obu wartości wraz z opisem źródła jest czytelniejszy niż zastępowanie starszego numeru nowszym bez wyjaśnienia historii urządzenia.

Rejestr zmian i historia wydań

Rejestr zmian opisuje kolejne wydania w uporządkowany sposób. Każdy wpis powinien wskazywać identyfikator wersji, datę opublikowaną przez producenta, zakres zmiany oraz dokument, z którego pochodzi opis. Jeżeli data nie jest dostępna, lepiej pozostawić ją niepodaną niż szacować ją na podstawie kolejności plików. Rejestr ma przedstawiać potwierdzone informacje, a nie rekonstruowaną historię.

Opis zmiany powinien rozróżniać poprawki błędów, zmianę obsługi podzespołów, modyfikację parametrów i zmianę interfejsu, jeśli producent tak je klasyfikuje. Nie należy dopisywać skutków, których dokumentacja nie potwierdza. Ogólne sformułowanie „ulepszenia działania” nie wyjaśnia zakresu aktualizacji. Jeśli producent podaje jedynie skrótowy komunikat, w rejestrze należy zachować jego sens i wskazać, że szczegółowy opis nie został udostępniony.

Historia powinna też odnotowywać relacje między wydaniami, takie jak wymaganie wcześniejszej wersji albo ograniczenie dotyczące wybranej rewizji sprzętu, o ile producent je podaje. Nie należy łączyć niezależnych linii wydań w jeden ciąg chronologiczny bez wyjaśnienia. Dwie gałęzie mogą być utrzymywane dla różnych wariantów. Sam numer lub data nie wystarczają do stwierdzenia, że jedno wydanie zastępuje wszystkie pozostałe.

Zakres zmian a parametry urządzenia

Zmiana oprogramowania może dotyczyć sposobu sterowania funkcją, obsługi czujnika, komunikacji lub prezentacji informacji. Nie oznacza to automatycznie zmiany parametrów fizycznych urządzenia, takich jak pojemność zbiornika czy pojemność akumulatora. Parametry te zależą od modelu i wariantu, a ich wartości należy odczytać z etykiety oraz karty produktu. Dokumentacja wersji powinna oddzielać zmianę programu od zmiany konstrukcji.

Jeśli w wydaniu zmienia się sposób obsługi danego podzespołu, należy ustalić, czy producent ograniczył zastosowanie do określonej rewizji sprzętowej. W przeciwnym razie nie wolno wnioskować, że każdy egzemplarz danego modelu obsługuje tę samą funkcję. Powiązanie wersji z konfiguracją powinno wynikać z wykazu zgodności lub informacji o wydaniu, a nie z samej obecności podobnego elementu w urządzeniu.

W dokumentacji parametrów może pojawić się termin „wartość deklarowana”, który oznacza dane podane przez producenta dla określonego modelu lub warunków. Nie jest to samo co wartość zmierzona dla konkretnego egzemplarza. Przy opisie zmian należy wskazać, czy modyfikacja dotyczy danych programu, parametrów produktu, czy metody ich prezentacji. Dzięki temu zapis nie sugeruje zmiany cechy fizycznej, jeśli zmienił się jedynie sposób raportowania.

Dokumentacja producenta i jej zakres

Podstawowe źródła informacji obejmują instrukcję, kartę produktu, wykaz wersji, informację o wydaniu i materiały serwisowe producenta. Dokumenty te mogą opisywać różne poziomy produktu. Instrukcja wyjaśnia obsługę, karta produktu podaje cechy modelu, a informacja o wydaniu dotyczy konkretnego oprogramowania. Nie należy traktować tych dokumentów jako zamiennych, jeśli każdy z nich odpowiada na inne pytanie.

Przy zapisie dokumentacji warto podać tytuł pliku lub dokumentu, jego oznaczenie, wersję i miejsce pozyskania, o ile te dane są dostępne. Pozwala to ustalić, do którego materiału odnosi się wpis w rejestrze. W przypadku plików elektronicznych znaczenie może mieć także nazwa pliku i data jego pobrania, ale sama data pobrania nie potwierdza daty wydania dokumentu ani programu.

Dokument producenta może dotyczyć całej rodziny urządzeń, a nie jednego wariantu. Wtedy należy sprawdzić zakres wymienionych modeli i ograniczeń. Jeżeli zakres jest niejednoznaczny, nie należy rozszerzać go na urządzenia o podobnej nazwie. W zapisie można wskazać, że dokument nie identyfikuje konkretnego wariantu. Oddzielenie zakresu potwierdzonego od nieokreślonego zapobiega pozornemu przypisaniu zgodności.

Zgodność wersji z modelem

Zgodność oznacza, że producent przypisał dane wydanie oprogramowania do określonego modelu lub wariantu w opisanym zakresie. Nie wynika ona wyłącznie z możliwości uruchomienia pliku ani z podobieństwa obudowy. W dokumentacji powinien znajdować się jednoznaczny identyfikator urządzenia albo wykaz obsługiwanych wariantów. Gdy dostępna informacja jest ogólna, należy zachować jej poziom szczegółowości i nie dopowiadać listy zgodnych modeli.

Weryfikacja przypisania obejmuje porównanie identyfikatora modelu, kodu wariantu i rewizji sprzętu z zakresem wskazanym przez producenta. W zależności od konstrukcji mogą być potrzebne wszystkie te elementy albo tylko część z nich. Dokument powinien wyjaśniać wymagane pola. Jeżeli jeden z identyfikatorów jest nieczytelny lub niedostępny, zapis należy oznaczyć jako niepełny, zamiast uznawać zgodność na podstawie innych podobnych danych.

Zgodność dokumentacji z modelem nie jest tym samym co potwierdzenie prawidłowego działania konkretnego egzemplarza. Dokumentacja określa zakres, dla którego wydanie jest przeznaczone, natomiast stan urządzenia może zależeć od jego konfiguracji, historii zmian lub uszkodzeń. Wpis o zgodności powinien więc wskazywać, czy odnosi się do deklaracji producenta, dokumentu technicznego, czy ustalenia dotyczącego konkretnego urządzenia.

Oznakowanie i powiązanie zapisów

Oznakowanie urządzenia i jego dokumentów powinno umożliwiać odtworzenie relacji między modelem, wariantem, rewizją sprzętu i wersją programu. Nie zawsze wszystkie informacje mieszczą się na etykiecie. W takim przypadku część danych może znajdować się w menu urządzenia lub dokumentacji. Ważne, by nie scalać ich w jeden ciąg bez opisania, które pole odpowiada któremu składnikowi.

W rejestrze można stosować osobne pola dla modelu, kodu wariantu, numeru seryjnego, rewizji sprzętu, wersji oprogramowania i źródła. Taka struktura ogranicza pomyłki wynikające z podobnych formatów oznaczeń. Numer seryjny i kod partii mogą pomóc zidentyfikować egzemplarz, ale nie powinny być opisywane jako wersja programu, jeśli producent nie nadał im takiego znaczenia.

Jeżeli dokumenty mają własne numery i rewizje, należy je zapisywać niezależnie od wersji urządzenia. Rewizja instrukcji może ulec zmianie bez zmiany programu, a nowa wersja programu może być opisana w niezmienionym pliku karty produktu. Powiązanie tych elementów w rejestrze pozwala ustalić, jakie źródło wykorzystano przy opisie urządzenia w danym momencie.

Przechowywanie i kontrola dokumentacji

Dokumenty powinny być przechowywane w sposób umożliwiający odróżnienie aktualnych plików od archiwalnych. Pomocne są czytelne nazwy zawierające model, typ dokumentu, identyfikator wersji i rewizję pliku, o ile takie dane istnieją. Nie należy nadpisywać wcześniejszego dokumentu bez zachowania informacji o jego poprzednim wydaniu, jeśli historia jest potrzebna do ustalenia, jakich danych użyto w przeszłości.

Wpis rejestru może zawierać lokalizację pliku, datę pozyskania, źródło i osobę lub proces wprowadzający zapis, jeżeli organizacja prowadzi takie pola. Sama struktura katalogów nie potwierdza autentyczności dokumentu. Należy zachować oryginalny plik producenta oraz odróżnić go od notatek i kopii roboczych. Pozwala to uniknąć przypisania interpretacji redakcyjnej do treści źródłowej.

Kontrola dokumentacji obejmuje także czytelność identyfikatorów i spójność odwołań. Jeśli w karcie produktu podano jedną wersję, a w pliku informacji o wydaniu inną, rozbieżność należy opisać i ustalić, czy dokumenty dotyczą różnych konfiguracji lub dat. Nie należy usuwać różnicy przez arbitralny wybór jednej wartości. W razie braku rozstrzygającego źródła należy zachować status informacji jako niepotwierdzonej.

Typowe nieporozumienia terminologiczne

Częstym błędem jest utożsamianie wersji oprogramowania z numerem modelu. Model identyfikuje rodzinę lub wariant produktu, natomiast wersja wskazuje wydanie programu. Oznaczenia mogą być wydrukowane obok siebie, przez co łatwo je pomylić. Rozstrzygające jest podpisanie pola przez producenta, a nie położenie ciągu znaków na etykiecie. W zapisie należy zachować nazwę pola źródłowego.

Innym nieporozumieniem jest traktowanie każdego wyższego numeru jako następcy wszystkich niższych. Różne warianty urządzenia mogą mieć odrębne linie wydań, a oznaczenie może obejmować poprawkę lub moduł. Bez opisu schematu numeracji nie da się pewnie ustalić kolejności ani zakresu zastąpienia. Należy korzystać z informacji producenta o relacjach między wydaniami.

Nie należy także utożsamiać zgodności z identycznością. Dwa warianty mogą być zgodne z tym samym wydaniem, lecz różnić się parametrami sprzętowymi. Z kolei urządzenia o tej samej nazwie mogą wymagać różnych wydań. Każdy taki wniosek wymaga potwierdzenia w dokumentacji. Jeżeli potwierdzenia brakuje, właściwym zapisem jest brak ustalenia, a nie przypuszczenie wynikające z podobieństwa oznaczeń.

Najczęstsze pytania

Czy numer seryjny jest wersją oprogramowania?

Nie, o ile producent nie określa go w ten sposób. Numer seryjny zwykle identyfikuje egzemplarz, a wersja opisuje wydanie programu.

Czy wyższy numer zawsze oznacza nowsze wydanie?

Nie zawsze. Znaczenie numeracji zależy od schematu producenta i może różnić się między liniami wydań lub modułami.

Gdzie należy odczytać wersję?

Źródło zależy od urządzenia. Informacja może być dostępna w jego menu, na etykiecie lub w dokumentacji producenta. Należy zapisać także miejsce odczytu.

Czy karta produktu potwierdza wersję konkretnego egzemplarza?

Niekoniecznie. Karta może dotyczyć modelu lub wariantu, a nie oprogramowania zainstalowanego w pojedynczym urządzeniu.

Czy zgodność z modelem potwierdza stan urządzenia?

Nie. Potwierdza przypisanie wydania do zakresu wskazanego przez producenta, ale nie opisuje samodzielnie historii ani stanu konkretnego egzemplarza.

Podsumowanie informacyjne

Dokumentacja wersji oprogramowania łączy identyfikator wydania z modelem, wariantem i rewizją sprzętu w zakresie określonym przez producenta. Pełny zapis powinien zachowywać oryginalne oznaczenia, źródła, historię zmian oraz ograniczenia zgodności. Rozdzielenie wersji programu od numeru modelu, numeru seryjnego i rewizji dokumentu ułatwia ustalenie, jakiej konfiguracji dotyczą poszczególne informacje techniczne.