Serwisy www B2B – dokumentacja

Z planowaniem jest jak z czytaniem instrukcji. Zaczynasz to robić, gdy jest już za późno.

O co chodzi?

Dokumentacja to DNA projektu – mówi co i jak ma działać i jakie spełniać standardy. Jeżeli czegoś dokłądnie nie opiszesz, pominiesz, to prawie na pewno będzie działać i wyglądać inaczej niż chcesz. Dzieje się tak, bo ludzie mają swoje wyobrażenia zarówno na temat najlepszych praktyk, odpowiedniej jakości jak i pojęcia “dobrze wykonanej pracy”  – co ważne definicje tych pojęć są zazwyczaj różne od Twoich. Dlatego jeżeli wiesz czego chcesz i bezkompromisowo dążysz do najwyższych standardów, to pisanie dokumentacji będzie dla Ciebie będzie czystą przyjemnością – to właśnie na tym etapie jesteś twórcą i architektem. A jeżeli nie wiesz czego tak naprawdę chcesz, to co wtedy? Wtedy znajdź sobie kogoś kto wie i to jak najszybciej i niech lepiej będzie to ktoś kto stoi po Twojej stronie, nie po stronie dostawcy.

Co wchodzi w skład?

Dokumentacja powinna odnieść się do minimum czterech segmentów: standardy kodowania, zgodność, front-end, back-end. Można także dołączyć do dokumentacji takie segmenty jak analityka, serwer oraz inne, jeżeli wymaga tego projekt.

Standardy kodowania

Ten segment jest dosyć generyczny, raz dobrze napisany służy co najmniej kilka miesięcy, aż do momentu gdy standardy się nie zmienią lub nie dojdą nowe możliwości.

Przestrzeganie, czasami bardzo rygorystycznych, standardów poprawia nie tylko wygląd, działanie i usability serwisu internetowego ale ma także duży wpływ na wizerunek firmy. Ten aspekt zostanie opisany szczegółowiej w innej części tej publikacji.

Zgodność w W3C

Zgodność ze standardami wytyczonymi z W3C oznacza zgodność z określonymi wersjami HTML, CSS ale nie tylko. Dotyczy to także zgodności ze standardami dostępności serwisów internetowych, które zostaną omówione szczegółowo w osobnym rozdziale.

Dostępność serwisu

Kwestie dostępności serwisów są dosyć złożone dlatego warto zapoznać się z takimi publikacjami jak na przykład http://www.hisoftware.com/why-hisoftware/thought-leadership/whitepapers/web-accessibility-handbook.aspx w których opisane są dokładne zasady, których przestrzeganie pozwala osiągnąć wysoki poziom dostępności treści.

Jednym ze standardów, które są powszechnie uznawane za wystarczające jest zgodność z Section 508, do pozostałych można zaliczyć WCAG 2.0 A, AA oraz AAA.

Dodatkowe wymagania

Technologia rozwija się bardzo szybko, dlatego poniższa lista szybko ulegnie rozszerzeniu albo zmianie. W momencie powstawania tej publikacji, do najpopularniejszych dodatkowych wymagań, można było dodać implementację: Rich Snippets http://snippets.org czy też protokołu Open Graph http://ogp.me/.

Kompatybilność

O ile jeszcze kilka lat temu wystarczyła zgodność z trzema najpopularniejszymi przeglądarkami, o tyle dzisiaj jest ich kilkanaście, czasami – pomimo tej samej nazwy – działających zupełnie inaczej, a do tego dochodzą liczne urządzenia, rozmiary ekranów, systemy operacyjne itd.

Zgodność jest jednym z tych kryteriów, które należy zoptymalizować czyli sprawdzić z jakich przeglądarek korzysta większość użytkowników i dostosować stronę pod te przeglądarki. Można oczywiśćie podejść do tematu bardzo restrykcyjnie i wygenerować długą listę przeglądarek z którymi serwis www ma być kompatybilny.

Lista przeglądarek z którymi strona www może być zgodna jest bardzo długa. Przeglądarki desktopowe:  IE, FireFox, Chrome, Safari, Opera, Conqueror (Linux). Przeglądarki mobilne: iPhone Safari, Blackberry webkit, Opera Mobile, Opera Mini, Firefox Windows Mobile: Mobile IE.

Do każdej przeglądarki powinno się dodać zgodność np. IE8+ co oznacza wszystkie przeglądarki od IE8 i późniejsze.

Należy wykazać się wiedzą na temat faktycznych możliwości przeglądarek, ponieważ niektóre z nich nie obsługują technologii, które zostały wskazane jako wymagane, jest tak chociażby z przeglądarką IE7, która wspiera Responsive Design. W tym celu warto sprawdzić, które przeglądarki spełniają jakie wymagania: http://caniuse.com.

Jakość kodu

Jeżeli kiedykolwiek w pełni samodzielnie programowałeś i uczestniczyłeś w wieloosobowych projektach, z pewnością doceniasz fakt chociażby dobrego rzetelnego komentowania i przestrzegania zasad formatowania kodu. Wydawałoby się to oczywiste, ale jeżeli tego nie zaznaczysz, możesz otrzymać kod pisany “na skróty”.

Przykładowe wymagania mogą wyglądać następująco:

  • obowiązkowy komentarz do każdego fragmentu kodu napisanego od początku lub modyfikowanego
  • poza uzasadnionymi wyjątkami nie wykorzystywanie CSS inline
  • zredukowanie do minimum ilości plików CSS
  • zredukowanie liczby klas CSS do minimum
  • wykorzystanie sprites images
  • wykorzystanie różnych rozdzielczości obrazków w zależności od gęstości ekranu
  • nazwy klas oraz ID należy pisać:
  • w krótki ale opisowy sposób
  • używać prefiksów do łatwej kategoryzacji
  • nie wykorzystywać dużych liter
  • używać “-” jako odstępu między słowami

Wbrew pozorom nawet ta wąska lista dobrych praktyk jest rzadko obecna w projektach, nie należy więc oczekiwać, że zostanie wdrożona w standardzie.

Frond end

Front End to opisywanie serwisu internetowego z poziomu użytkownika. Nie chodzi tutaj o szczegółowe odnoszenie się do każdej strony (templatki) z osobna, aczkolwiek i to podejście jest jak najbardziej pożądane o ile można się odwołać do już istniejących templatek albo lub mockupów.

Najczęściej jednak wystarczy opisywać funkcjonalności, które mają się pojawić na stronie.

Najprostszym przykładem będzie funkcjonalność rejestracji w serwisie. W tym wypadku należy dokładnie opisać formularz, który ma wypełnić użytkownik, co oznacza zarówno nazwanie pól formularza (np. imię), typów pola (np. input), ograniczenia pól (np. długość) jak również tytuł formularza, opis formularza, a nawet opis pomocy do każdego pola czy nazwę przycisku zapisującego formularz. Jeżeli podejdziesz do tematu na tym poziomie szczegółowości, osiągniesz cel szybko i sprawnie. Oczywiście, najpierw musisz wiedzieć czego chcesz – bezmyślne kopiowanie gotowców z różnych źródeł nie ma sensu i prowadzi wcześniej czy później do zamieszania jeżeli nie ośmieszenia.

Rejestracja ma także następne etapy, i te etapy także należy opisać. Jak chociażby potwierdzenie mailowe, w tym kiedy jest wysyłane, jaka jest dokładna treść e-mail w tym (nadawca, tytuł, link oraz jego nazwa, treść, stopka). W skład opisu powinno wchodzić także co dzieje się po kliknięciu w link, a co się dzieje gdy ktoś nie kliknie na link przez na przykład kilka dni. W obydwu przypadkach należy opisać to jako elementy funkcjonalności “rejestracja”, starając się dokładnie pisać teksty, które powinny się tam znaleźć.

Praktyka wskazuje, że 50% tych tekstów jest potem zmieniana i modyfikowana, by wpasować się w layout strony. Na początkowym etapie, usprawnia pracę i minimalizuje ilość, zapytań, domysłów i ewentualnych niewłaściwych interpretacji, które kosztują nas dodatkowy czas, nerwy i pieniądze.

W ten sposób uzyskasz mniej więcej taką strukturę:

  • nazwa-funkcjonalności-na-przykład-logowanie
  • nazwa-etapu-na-przyklad-wypelnienie-formularza-ze-strony-glownej
  • opis-ogólny
  • nazwa formularza i wprowadzenie
  • opis formularza
  • nazwa pola, typ pola, ograniczenia pola, komunikat błędu
  • opis pomocy
  • nazwa-następnego-etapu

Back end

Systemy CMS

Systemy CMS wymagają co najmniej konfiguracji ale najczęściej mocnej personalizacji albo nawet głębszych przeróbek. Zazwyczaj bez tego nie osiągniesz zamierzonego efektu. Większość CMS jest jednak podobną, modułową budowę. Oznacza to ni mniej ni więcej to, że jeżeli gdzieś będziesz przechowywał logotypy Klientów i raz że będzie ich sporo, a dwa że będziesz chciał je wykorzystywać w kilku miejscach równocześnie w różny sposób, to warto stworzyć dla niego moduł o nazwie logotypy-klientów. Taki moduł musi być opisany co do tego jak te logotypy powinny być gromadzone i jakie dodatkowe właściwości należy do każdego logotypu dodać.

Przykład z logotypami jest o tyle dobry, że jest pozornie trywialny – ot wystarczy przecież załadować obrazek i gotowe –  jednak w zależności od wymagań może się znacznie skomplikować, na przykład:

  • moduł o nazwie “logotypy” w którym gromadzimy bitmapy w określonym przez nas formacie, np. PNG o ściśle określonym formacie: 300x200px, na przeźroczystym tle.
  • Każdy logotyp musi zostać zlinkowany z Klientem opisanym w module “Klienci”
  • Każdy obrazek powinien mieć domyślną nazwę złożoną z nazwy podpiętego pod logotyp Klienta.
  • Nazwa powinna być pisana zawsze małymi literami, a słowa rozdzielane znakiem “-”.
  • ALT jest tworzony automatycznie z nazwy pliku, przy czym może być ręcznie modyfikowany
  • Każdy logotyp powinien być widoczny na liście w formie miniatury, która po najechaniu kursorem myszki zostaje wyświetlona na osobnej warstwie w pełnej rozdzielczości.
  • Możliwe jest wyszukiwanie logotypów po nazwie, nie krótszej niż 3 znaki

Opublikowano

w

,

przez