Alternatywny do pomocy HTML

Obecnie używamy systemu o nazwie AsciiDoc, który pozwala nam tworzyć dokumentację za pomocą prostego znacznika tekstowego. Z tego możemy wygenerować wiele formatów wyjściowych. Używamy tylko formatów wyjściowych pdf i chm.

Zastanawiałem się, czy istnieje alternatywa dla chm? To, czego szukam, to coś, czego można używać w trybie offline (jest to ważne, ponieważ wielu naszych użytkowników znajduje się w bardzo odległych miejscach) z naszym oprogramowaniem. Powinien mieć indeks (może być tak prosty jak strona html z hiperłączami), powinien być możliwy do przeszukiwania i powinien mieć mechanizm, który umożliwia wywoływanie określonych wpisów z kodu (podobnie jak pomoc kontekstowa).

Dwie rzeczy, które są przeciwko PDF w tym przypadku to:

1. Pomoc kontekstowa nie jest opcją
2. Ogólnie dokument jest dość duży
3. PDF jest bardziej odpowiedni do dokumentacji drukowanej niż pomoc kontekstowa

Chciałbym użyć HTML. Jedynym problemem związanym z html jest to, że nie potrafię wymyślić sposobu automatycznego wyszukiwania słów kluczowych (oprócz funkcji ctrl + f w przeglądarkach - chciałbym czegoś bardziej widocznego). Nie mogę też znaleźć metody automatycznego generowania hiperłącza indeksu słów kluczowych. Pomoc kontekstowa byłaby prosta ze względu na tagi sekcji - mógłbym po prostu przekazać adres URL strony i interesującej mnie sekcji do domyślnej przeglądarki i ta strona powinna załadować się do właściwej sekcji.

Moje wymagania brzmią okropnie jak chm - tak. Wymodelowałem swoje wymagania na podstawie chm. Jedynym powodem, dla którego nie lubię chm, jest sposób, w jaki kod współdziała z nim za pomocą mapidów i tym podobnych. Wolałbym raczej przechowywać listę tekstową (która jest generowana automatycznie dla mnie), której mój kod może użyć do uzyskania dostępu do kontekstowej części dokumentacji.

Wyobrażam sobie skrypt, który przejdzie przez pliki wyjściowe HTML i wygeneruje stronę indeksu, która po prostu zawiera listę znalezionych słów kluczowych. oczywiście powinien istnieć mechanizm wykluczania słów, aby ignorować takie słowa jak: to, to, itd. Ta część byłaby stosunkowo łatwa do napisania. Druga część wymagałaby jakiegoś skryptu, aby zebrać bazę słów kluczowych i ich lokalizację w tekście HTML. Myślę, że będzie to trudna część, wraz z zapewnieniem mechanizmu wyszukiwania w przeglądarce.

Wszelkie pomysły dotyczące alternatyw byłyby mile widziane. Chciałbym użyć wiki lub zestawu statycznych stron HTML przechowywanych gdzieś na serwerze internetowym, ale mamy krytyczny wymóg używania offline. Po prostu umieszczenie html na lokalnym dysku nie zapewnia nam potrzebnych potrzeb wyszukiwania.

EDYTOWAĆ:

Projektuję oprogramowanie używane w przemyśle wydobywczym. Wiele kopalni jest bardzo odległych i nie ma dostępu do Internetu w żaden znaczący sposób. Nie ma nic złego w pdf, html lub chm (poza tym, że się starzeje). Gdybym mógł wyświetlić plik pdf we właściwej lokalizacji (tj. Pomoc kontekstową), użyłbym go. Prawie kusi mnie, aby napisać własną - w zasadzie byłaby to przenośna wiki. Mówiąc o tym, jeśli sugerujesz przenośne wiki - musisz pomyśleć o użytkowniku końcowym, który może nie mieć doświadczenia w korzystaniu z takich narzędzi. To musi być bardzo proste. To było piękno chm, praca z nim jest uciążliwa, ale podobają się użytkownikom końcowym.

Jeśli jesteś przygotowany do napisania swojej pomocy w znacznikach XML DocBook zamiast HTML, DocBook obsługuje tworzenie WebHelp: http://wiki.docbook.org/WebHelp

Dokumentacja WebHelp jest również prezentacją danych wyjściowych: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/content/ch01.html

Daje internetowy format pomocy HTML, który obejmuje:

• Wyszukiwanie pełnotekstowe za pomocą:
  • Wsparcie dla języka angielskiego, francuskiego i niemieckiego. Obsługę stempla można dodać dla innych języków, implementując stemmer.
  • Obsługa języka chińskiego, japońskiego i koreańskiego za pomocą kodu z wyszukiwarki Lucene.
  • Podświetlanie wyszukiwania, które pokazuje, gdzie szukany termin pojawia się w wynikach.
  • Wyniki wyszukiwania mogą zawierać krótkie opisy celu.
• Panel spisu treści ze składanym drzewem spisu treści.
• Automatyczna synchronizacja okienka treści i spisu treści.
• Zaimplementowano spis treści i panel wyszukiwania bez użycia zestawu ramek.
• Plik build.xml Ant do generowania danych wyjściowych.

Twórcy RoboHelp zajęli się innymi rzeczami i wrócili, aby stworzyć lepszą alternatywę. Sprawdź Flare MadCap - obsługuje wiele formatów wyjściowych, generuje indeks i udostępnia funkcję wyszukiwania działającą lokalnie (przez JavaScript).

Używamy Adobe RoboHelp do generowania różnych stylów dokumentacji pomocy offline. Zapewnia wiele opcji wyjścia i integracji treści. Wspaniałą rzeczą w tym narzędziu jest to, że możesz przekazać go osobom niebędącym programistami i uzyskać świetną zawartość przy niewielkim wysiłku integrującą się z Twoim rozwiązaniem.

Sam CHM się starzeje, a Microsoft przeniósł się również na nowsze rzeczy: http://msdn.microsoft.com/en-us/library/bb164608(v=vs.80).aspx

Ale jeśli naprawdę chcesz uniknąć konwersji pomocy na istniejący system i zastanawiasz się, jak zapewnić wyszukiwanie i wyszukiwanie słów kluczowych w statycznych plikach pomocy, oto dwa pomysły:

• dodaj do projektu mały serwer HTTP tylko do lokalnego hosta, aby obsługiwał witrynę z dokumentacją. Problemy dotyczą tego, kiedy lub jak uruchomić / zatrzymać ten serwer HTTP i / lub utrzymać go w działaniu. Alternatywą byłoby wdrożenie niestandardowego schematu URL, ale wiązałoby to cię z jedną przeglądarką i jest o wiele więcej pracy ( i mogę powiedzieć )

• napisać wyszukiwarkę JavaScript. JavaScript w dowolnej przeglądarce staje się obecnie dość szybki i wydajny. Indeks słów kluczowych może być łatwo przechowywany w JSON, i uruchomiłem regularne wyrażenia na lokalnych plikach z całkiem dobrymi wynikami.

To, czego szukam, to coś, czego można używać w trybie offline (jest to ważne, ponieważ wielu naszych użytkowników znajduje się w bardzo odległych miejscach) z naszym oprogramowaniem.

Korzystamy z RoboHelp w mojej firmie i życzymy powodzenia w udostępnianiu plików pomocy offline, ponieważ często użytkownicy przechodzą z obszarów z dostępem do sieci do obszarów bez.

Powinien być możliwy do przeszukiwania i powinien mieć mechanizm, który umożliwia wywoływanie określonych wpisów

Korzystamy z niektórych stron w RoboHelp, aby wyjaśnić użycie niektórych pól na ekranie. Jesteśmy w stanie wyświetlać wyskakujące okienka dla tych pól, które pojawiają się po kliknięciu. RoboHelp ma również bardzo dobrą zdolność wyszukiwania i automatycznie generowany indeks. Zawsze miałem szczęście, szukając go. To może nie być dla ciebie dużym problemem, ale jesteśmy w stanie poprosić kogoś o aktualizację dokumentacji, ponieważ RoboHelp jest dość łatwym w użyciu programem.