Alternatif untuk Bantuan HTML

Kami saat ini menggunakan sistem yang disebut AsciiDoc yang memungkinkan kami membuat dokumentasi dalam markup teks sederhana. Dari sana kita dapat menghasilkan beberapa format output. Kami hanya menggunakan format pdf output dan output chm.

Saya bertanya-tanya apakah ada alternatif untuk chm? Apa yang saya cari adalah sesuatu yang dapat digunakan secara off-line (ini penting karena beberapa pengguna kami berada di tempat yang sangat terpencil) dengan perangkat lunak kami. Itu harus memiliki indeks (bisa sesederhana halaman html dengan istilah hyperlink), itu harus dapat dicari dan harus memiliki mekanisme yang memungkinkan entri tertentu dipanggil dari kode (mirip dengan bantuan konteks sensitif).

Dua hal yang bertentangan dengan PDF dalam hal ini adalah:

1. Bantuan sensitif konteks bukan pilihan
2. Umumnya dokumennya agak besar
3. PDF lebih cocok untuk dokumentasi cetak daripada bantuan konteks sensitif

Yang saya inginkan adalah menggunakan html. Satu-satunya masalah dengan html adalah bahwa saya tidak bisa menemukan cara untuk secara otomatis menyediakan pencarian kata kunci (selain dari fungsionalitas ctrl + f browser - saya ingin sesuatu yang lebih jelas). Saya juga tidak bisa menemukan metode untuk secara otomatis menghasilkan indeks kata kunci yang hyperlink. Bantuan sensitif konteks akan sederhana karena tag bagian - Saya bisa dengan mudah melewatkan url halaman dan bagian yang saya minati ke browser default dan halaman itu harus memuat ke bagian yang benar.

Persyaratan saya terdengar sangat buruk seperti chm - benar. Saya memodelkan persyaratan saya dari chm. Satu-satunya alasan saya tidak suka chm adalah karena cara kode berinteraksi dengannya menggunakan mapid dan semacamnya. Saya lebih suka menggunakan menyimpan daftar teks biasa (yang secara otomatis dihasilkan untuk saya) yang dapat digunakan kode saya untuk mengakses bagian sensitif konteks dari dokumentasi.

Saya membayangkan skrip yang akan melalui file output html dan menghasilkan halaman indeks yang hanya berisi daftar kata kunci yang ditemukannya. jelas harus ada mekanisme pengecualian kata untuk mengabaikan kata-kata seperti: itu, itu, adalah, dll. Bagian ini akan relatif mudah untuk ditulis. Bagian kedua akan membutuhkan semacam skrip untuk mengumpulkan basis data kata kunci dan lokasinya dalam teks html. Saya pikir ini akan menjadi bagian yang sulit bersama dengan menyediakan mekanisme pencarian di dalam browser.

Setiap ide tentang alternatif akan dihargai. Saya ingin menggunakan wiki atau set halaman html statis yang dihosting di server web di suatu tempat, tetapi kami memiliki persyaratan penggunaan offline yang kritis. Cukup menempatkan html di drive lokal tidak memberi kami persyaratan pencarian yang kami butuhkan.

EDIT:

Saya merancang perangkat lunak yang digunakan oleh industri pertambangan. Banyak tambang sangat terpencil dan tidak memiliki akses ke internet dengan cara apa pun yang berarti. Tidak ada yang salah dengan pdf atau html atau chm (kecuali bahwa itu semakin tua). Jika saya bisa menampilkan file pdf di lokasi yang benar (yaitu bantuan konteks sensitif) saya akan menggunakannya. Saya hampir tergoda untuk menulis sendiri - pada dasarnya ini adalah wiki portabel. Omong-omong, jika Anda menyarankan wiki portabel - Anda harus memikirkan pengguna akhir yang mungkin tidak memiliki pengalaman dalam menggunakan alat tersebut. Itu harus mati sederhana. Itu adalah keindahan chm, itu menyakitkan untuk bekerja dengan tetapi pengguna akhir menyukainya.

Jika Anda siap untuk menulis bantuan Anda dalam markup DocBook XML daripada HTML, DocBook memiliki dukungan untuk memproduksi WebHelp: http://wiki.docbook.org/WebHelp

Dokumentasi WebHelp juga merupakan demo dari output: http://docbook.sourceforge.net/release/xsl/current/webhelp/docs/content/ch01.html

Ini memberi Anda format bantuan HTML berbasis Web yang mencakup:

• Pencarian teks lengkap dengan:
  • Dukungan yang kuat untuk bahasa Inggris, Prancis, dan Jerman. Dukungan induk dapat ditambahkan untuk bahasa lain dengan menerapkan stemmer.
  • Dukungan untuk bahasa Cina, Jepang, dan Korea menggunakan kode dari mesin pencari Lucene.
  • Sorotan pencarian yang menunjukkan di mana istilah yang dicari muncul di hasil.
  • Hasil pencarian dapat mencakup deskripsi singkat dari target.
• Daftar isi panel dengan pohon TOC dilipat.
• Sinkronisasi otomatis panel konten dan TOC.
• TOC dan panel pencarian diimplementasikan tanpa menggunakan frameset.
• File semut build.xml untuk menghasilkan keluaran.

Pencipta RoboHelp melanjutkan ke hal-hal lain, dan telah kembali untuk membuat alternatif yang lebih baik. Lihat MadCap's Flare - ini mendukung beragam format output, menghasilkan indeks, dan memasok fungsi pencarian yang beroperasi secara lokal (via JavaScript).

Kami telah menggunakan Adobe RoboHelp untuk menghasilkan berbagai gaya dokumentasi bantuan luring. Ini memberikan banyak pilihan output dan integrasi untuk konten. Hal yang hebat tentang alat ini adalah Anda dapat memberikannya kepada non pengembang dan mendapatkan konten yang hebat dengan sedikit usaha terintegrasi ke dalam solusi Anda.

CHM sendiri semakin tua, dan Microsoft juga beralih ke hal-hal yang lebih baru: http://msdn.microsoft.com/en-us/library/bb164608(v=vs.80).aspx

Tetapi jika Anda benar-benar ingin menghindari mengonversi bantuan Anda ke sistem yang ada, dan mencari cara untuk menyediakan pencarian dan pencarian kata kunci pada file bantuan statis, berikut adalah dua ide:

• tambahkan server HTTP localhost-only kecil ke proyek untuk melayani situs web dengan dokumentasi. Masalahnya adalah kapan atau bagaimana memulai / menghentikan server HTTP ini dan / atau membuatnya tetap berjalan. Alternatif akan menerapkan skema URL khusus, tetapi ini akan mengikat Anda ke satu browser dan jauh lebih banyak pekerjaan ( dan saya tahu )

• menulis mesin pencari JavaScript. JavaScript di browser apa pun semakin cepat dan performan akhir-akhir ini. Indeks kata kunci dapat dengan mudah disimpan di JSON, dan saya telah menjalankan expresson reguler pada file lokal dengan hasil yang cukup bagus.

Apa yang saya cari adalah sesuatu yang dapat digunakan secara off-line (ini penting karena beberapa pengguna kami berada di tempat yang sangat terpencil) dengan perangkat lunak kami.

Kami menggunakan RoboHelp di perusahaan saya dan kami beruntung membuat file bantuan tersedia offline karena kami sering memiliki pengguna yang pergi dari daerah dengan akses jaringan ke daerah tanpa.

Itu harus dapat dicari dan harus memiliki mekanisme yang memungkinkan entri tertentu untuk dipanggil

Kami menggunakan beberapa halaman di RoboHelp untuk menjelaskan penggunaan bidang tertentu di layar. Kami dapat memiliki munculan untuk bidang-bidang yang muncul setelah klik. RoboHelp juga memiliki kemampuan pencarian yang sangat bagus dan indeks yang dihasilkan secara otomatis. Saya selalu beruntung mencari itu. Ini mungkin bukan masalah besar bagi Anda, tetapi kami dapat meminta siapa pun memperbarui dokumentasi karena RoboHelp adalah program yang cukup mudah digunakan.