Od nieporęcznego 7000-stronicowego pliku PDF do użytecznej pomocy internetowej
Początkowa sytuacja niezbyt inteligentna: Trudności w korzystaniu z rozbudowanej specyfikacji
W naszej codziennej pracy programistycznej często mamy do czynienia z konwersją z i do Microsoft Word. W tym celu dużo pracujemy z ECMA-376, specyfikacją OOXML. Każdy, kto kiedykolwiek miał dostęp do tego ~7000-stronicowego zbioru informacji, wie, że praca z tą specyfikacją w formacie PDF, Word lub, powiedzmy, drukowanych dokumentach jest naprawdę uciążliwa.
Podczas pracy ze specyfikacją szczególnie ważne jest szybkie wyszukiwanie informacji. Spróbuj otworzyć Word Część IV tylko z wersji 1. Wyświetlenie dokumentu zajmuje średnio 5 minut. Teraz spróbuj przeszukać ten obszerny dokument. Zobaczysz, że minie trochę czasu, zanim wyszukiwanie będzie aktywne i będzie odpowiadać. Podobnie wygląda sytuacja z wersjami PDF. Nie jest to stan, z którym mogą pogodzić się deweloperzy potrzebujące szybkiego dostępu do konkretnych informacji.
smart cel: Łatwy dostęp do informacji ze specyfikacji
W tym przypadku potrzebna jest prezentacja i szybki dostęp do wszystkich informacji, najlepiej w pełni responsywnym układzie, z dobrą możliwością nawigacji w treści, z podświetlaniem składni i oczywiście szybkim wyszukiwaniem pełnotekstowym.
Konwersja do pomocy internetowej, HTML5
Aby zrealizować te cele, konwersja specyfikacji do HTML5 była oczywistym wyborem. Jak dobrze, że mamy środowisko konwersji, które zostało zaprojektowane dokładnie do takich zadań.
Skonfigurowaliśmy więc własne środowisko konwersji, c-rex.net.DTS, aby wyodrębnić wszystkie informacje z Word i przenieść tę zawartość do DITA, a stamtąd do pomocy internetowej, która spełnia wszystkie wymagania naszej codziennej działalności. Konwersja ta została przeprowadzona całkowicie automatycznie.
Prawidłowo, formatem pośrednim jest DITA. W ten sposób jesteśmy na dobrej drodze do ustrukturyzowanego i przede wszystkim modułowego działania. Świat jest otwarty - od tłumaczenia maszynowego po dostarczanie treści sterowanych przez użytkownika, na przykład w oparciu o iiRDS. Nawiasem mówiąc, zawartość DITA jest dostępna do pobrania w zasobach c-rex.net.
Najważniejsze cechy Webhelp w porównaniu z rozwiązaniem PDF oryginalnej specyfikacji ECMA
Oto najważniejsze z nich, tj. to, co naszym zdaniem sprawia, że praca ze specyfikacją w formacie HTML jest znacznie inteligentniejsza niż praca z wersjami Word lub PDF.
Reprezentacja
responsywny vs. nieresponsywny w Word
Wyszukiwanie
Wyszukiwanie pełnotekstowe vs. ograniczone do danego pliku Word
Sugestie wyszukiwania w polu wyszukiwania
Czas wyszukiwania to kilka sekund w porównaniu z kilkoma minutami w 5000-stronicowym pliku
Ranking wyników wyszukiwania vs. brak rankingu wyników wyszukiwania w Word
Nawigacja i orientacja w treści
poprzez spisy treści i spisy rozdziałów vs. Spis treści tylko na początku pliku Word
Podświetlanie składni
Podświetlanie składni vs. brak podświetlania składni w Word
Nikt nie jest doskonały: małe dziwactwa implementacji HTML
Zdajemy sobie sprawę, że ta w pełni automatyczna konwersja nie zapewnia idealnego wyniku. I wcale nie musi! Ale wrócimy do tego za chwilę. Tutaj pokazujemy pewne niedociągnięcia w wyniku konwersji, ale my, deweloperzy, możemy z łatwością z nimi żyć.
zbędne dwukropki w niektórych elementach, np. Uwagi i Przykład
brak numeracji rozdziałów, zwłaszcza w przypadku odniesień, które nie pokazują tekstu tytułu, ale numer sekcji.
Wnioski: Skoncentruj się na tym, co najważniejsze i zignoruj szczegóły, które nie są istotne dla danego przypadku użycia.
Ten projekt jest dobrym przykładem realizacji projektu, w którym nie zaczęliśmy od maksymalnego wykonalnego, ale wdrożyliśmy rozwiązanie oparte na bardzo konkretnym przypadku użycia.
Celowo zdystansowaliśmy się tutaj od postawy, którą wielokrotnie obserwowaliśmy: Tendencja do bycia perfekcyjnym, do skupiania się na wielu drobiazgach, które generują wiele wysiłku. Zbyt często prowadzi to do zbyt długiego czasu realizacji projektu. Albo prowadzi do tego, że dbałość o szczegóły może nawet spowodować całkowite niepowodzenie projektów.
W przypadku OOXML-Spec mamy do czynienia ze specjalnym przypadkiem użycia: Książka referencyjna dla deweloperzy, które muszą pracować z programem Word. W tym przypadku ważne jest, aby informacje można było szybko znaleźć. deweloperzy - grupa docelowa tej implementacji - nie są tak naprawdę zainteresowani drobnymi dziwactwami opisanymi powyżej. Jeśli ja, jako deweloper, mogę uzyskać wynik za pomocą zaledwie kilku kliknięć, szybko pomaga mi to w codziennej pracy i cieszę się, że nie muszę już zmagać się z Word lub nieporęcznymi, niereagującymi plikami PDF.
Tak więc wygenerowaliśmy tutaj prawdziwą wartość dodaną dla deweloperzy przy nie 100% podejściu i przy możliwym do opanowania wysiłku, ponieważ po prostu nie dbaliśmy o wspomniane szczegóły. Jeśli jest to ważne dla innych przypadków użycia, możesz oczywiście zainwestować więcej czasu i pieniędzy, aby jeszcze bardziej zoptymalizować wynik.
Jeśli chcesz, sam spójrz na wynik: Przykład OOXML na stronie c-rex.net.