Dartdoc: Sulit untuk menemukan konten menggunakan pencarian browser biasa

bagaimana kalian menyelesaikan ini? Saya memiliki masalah ini di halaman flutter saya

Judul masalah salah. Seharusnya: "Jadikan konten halaman dokumentasi dapat dicari dengan CTRL-F".

Saya baru saja mencoba mencari MaterialApp untuk kata "tema" untuk menemukan argumen konstruktor. Fungsi pencarian melewati ENAM PULUH TUJUH contoh "tema" di bilah sisi di bawah CLASSES sebelum mencapai entri di bagian dokumentasi halaman.

Saya merasa sangat frustrasi setiap kali saya mengalami masalah ini. Itu terjadi beberapa kali sehari saat saya bekerja dengan Flutter.

Bagaimana perasaan Anda jika Anda tidak dapat menggunakan CTRL-F untuk mencari file yang dilihat dalam pencarian kode?

Label enhancement salah. Ini pasti bug.

P2 berarti mengabaikan selamanya. Saya kira itu juga digunakan untuk "bekerja sebagaimana dimaksud".

Apakah ini bagian dari Praktik API Jika Anda Membenci Pelanggan Anda - Teknik #4: Sembunyikan Dokumen API dari Mesin Pencari ?

Saya benar-benar mengerti bahwa ini adalah masalah yang membuat frustrasi. Tetapi konten _is_ dapat dicari melalui Ctrl+F, hanya saja membosankan untuk melakukannya.

Saat bekerja, ada cara lain yang lebih dapat dinavigasi untuk menggunakan dokumen:

• Di pohon sumber itu sendiri (klik ctrl/cmd di IDE)
• Melalui pembaca docset offline atau hanya mengunduh seluruh docset secara lokal: https://github.com/flutter/flutter/issues/9955#issuecomment -444702105

Saya setuju tidak satu pun dari itu adalah solusi untuk bug khusus ini. Sebagian masalahnya, AFAICT, adalah tidak ada cara mudah untuk melakukan ini. Sebagai pemeriksaan kewarasan dalam hal ini, dokumen MSDN bekerja dengan cara yang sama, seperti halnya dokumen Javadoc biasa, dan dokumentasi SDK Android, dll.

Bagian dari masalahnya adalah bahwa ini sulit untuk diperbaiki. Jika kami mengacaukan teks di bilah sisi sehingga tidak dapat dicari, kami hampir pasti akan merusak aksesibilitas di sana (dan siapa pun yang benar-benar mencoba mencari di sana dengan ctrl+f untuk beberapa alasan). Membuat komponen custom find yang mencari bagian utama terlebih dahulu (misalnya sesuatu seperti apa yang terjadi di Google docs ketika Anda menekan Ctrl+F ) mungkin layak, tetapi tidak sepele dan akan menjadi peningkatan yang cukup besar.

Saya akan senang jika terbukti sebaliknya...

P2 berarti mengabaikan selamanya.

Bukan itu P3 . Serius meskipun sebagian besar perbaikan bug dan peningkatan yang kami buat di sini mungkin P2.

Catatan: kami memiliki pedoman tentang bagaimana kami memprioritaskan, di README: https://github.com/dart-lang/dartdoc/#issues -and-bugs. Saya pikir ini bisa masuk ke P1 atau P2. Mencoba untuk tidak menyenangkan, saya tidak berpikir masalahnya adalah _widespread_, yang berarti "ENAM PULUH TUJUH contoh "tema" di bilah sisi" adalah outlier, tidak umum. Saya berpendapat "Kutil tampilan kecil tidak secara signifikan menghambat navigasi, tidak meluas" menempatkannya di P2.

Saya berharap ada trik HTML / z-index yang mudah untuk membalik pesanan, tetapi saya tidak menemukan apa pun. Mungkin pesanan fleksibel ? (Situs saat ini menggunakan flex dalam tata letak.)

Saya ingin tahu apakah kita hanya menginginkan sesuatu yang sederhana seperti menyediakan beberapa cara untuk membuat isi/konten utama mengambil layar penuh, sehingga akan lebih mudah dicari. Kami bahkan dapat menampilkan semacam snackbar atau sesuatu yang menyarankan pengguna mengklik tombol itu jika kami mendeteksi mereka menekan ctrl+f.

Solusi:

1. Libatkan spesialis UX untuk memperbaiki masalah ini. Untuk menghemat waktu, Anda bisa mencari web developer yang juga memiliki pelatihan UX. Manfaat tambahannya adalah mereka dapat memperbaiki masalah kegunaan lainnya dengan situs.
2. Pindahkan daftar CLASSES ke halamannya sendiri. Daftar paket Flutter berisi 1.058 entri dan terlalu besar untuk menjadi menu navigasi biasa. Ganti dengan bagian "Kelas Terkait". Lihat "Desain Menu: Daftar Periksa 15 Panduan UX untuk Membantu Pengguna, Butir 10 Menyediakan menu navigasi lokal untuk konten yang terkait erat (Nielsen Norman Group)" .
3. Letakkan konten di sebelah kiri dan kolom CLASSES di sebelah kanan/samping halaman. Pilihan desain ini didukung oleh riset pengguna .
4. Gunakan CSS untuk mengatur ulang urutan kolom:
   html <html> <body> <div style="display:flex; flex-direction:row;"> <div style="order:2; flex-grow:1; margin-left:1em;"> <h1>Heading1</h1> <p>Content1</p> </div> <div style="order:1; flex-grow:0;"> <h1>Sidebar</h1> <p>Content2</p> </div> </div> </body> </html>
   

@srawlins menulis:

Mencoba untuk tidak menyenangkan, saya tidak berpikir masalah ini tersebar luas, yang berarti "ENAM PULUH TUJUH contoh "tema" di bilah sisi" adalah hal yang aneh, tidak umum. Saya berpendapat "Kutil tampilan kecil tidak secara signifikan menghambat navigasi, tidak meluas" menempatkannya di P2.

Coba kembangkan aplikasi Flutter dan lihat berapa kali Anda mengalami masalah ini. Mencari hampir semua argumen atau atribut akan masuk ke menu. Itu terjadi lebih banyak dengan argumen yang rumit, karena itulah yang kemungkinan besar perlu Anda cari.

Masalahnya ada pada dokumen Flutter, tetapi perbaikannya memerlukan perubahan pada perkakas Dart. Tolong jangan menolak untuk memperbaiki ini karena itu tidak diperlukan untuk "sebagian besar paket dart". Jangan biarkan birokrasi menghalangi produk Anda untuk memenuhi kebutuhan pengguna. Flutter sangat penting untuk profitabilitas jangka panjang Alphabet. Saat Flutter lebih mudah digunakan, lebih banyak pengembang aplikasi akan menggunakannya, aplikasi Android mereka akan memiliki kualitas yang sama dengan versi iOS, yang akan meningkatkan popularitas Android, yang memberikan perilaku pengguna (melalui Analytics dan Chrome ) yang penting untuk iklan Google -algoritma pencocokan, yang menghasilkan hampir semua uang perusahaan.

@dnfield menulis:

jika kami mendeteksi mereka menekan ctrl+f

Itu akan mengejutkan, membingungkan, dan memperlambat pengguna dan akan mengganggu pembaca layar. Anda tidak boleh membuat halaman dokumentasi menjadi aplikasi interaktif. Elemen interaktif dapat menambahkan fungsionalitas, tetapi tidak pernah diperlukan. Dokumen paket Dart menyediakan satu elemen interaktif: kotak pencarian. Ini adalah formulir bidang tunggal yang menunjukkan daftar kecocokan dalam sembulan. Tetapi mengirimkan formulir tidak menunjukkan daftar kecocokan ini, melainkan mengarah ke hasil pencarian pertama. Ini membuat fungsi pencarian kurang dapat diakses dan digunakan. Jadi saat ini, halaman berisi satu elemen interaktif dan itu merusak kegunaan. Tolong jangan tambahkan lagi.

Ya, saya baik-baik saja dengan tidak menambahkan lebih banyak, tetapi saya curiga pertanyaan UX di sini adalah bagaimana membuat dokumen lebih mudah ditemukan daripada harus berfokus pada "bagaimana cara membuat ctrl + F" berfungsi.

Mungkin juga akan membantu untuk menemukan contoh dokumen berbasis HTML yang berfungsi dengan baik dalam hal ini, karena setiap contoh utama yang dapat saya pikirkan berperilaku persis seperti yang dilakukan dartdoc di sini (dan ada contoh yang tampaknya sama buruknya bagi saya dalam hal " daftar kelas/metode di sebelah kiri memiliki banyak kata yang saya cari di badan").

Pustaka lain memecahkan masalah ini dengan mengatur API ke dalam modul yang diberi nama dengan benar. Modul menunjukkan struktur perpustakaan dan konsep-konsep penting. Mereka membantu pengguna baru mempelajari API. Modul juga menyediakan dokumentasi penting untuk insinyur yang sibuk mengerjakan kode yang ada.

Modul inti Flutter ( material , cupertino , dan widgets ) masing-masing mengekspor ulang hampir seluruh Flutter API.

Organisasi modul Flutter yang buruk adalah kesalahan yang seharusnya diperbaiki sebelum versi 1.0. Ini adalah jenis hal yang ditemukan dan diperbaiki oleh PM. Google memberikan hak veto kepada para insinyurnya atas prioritas produk dan ini berarti para PM mengalami kesulitan dalam menyelesaikan sesuatu. Dapat dikatakan bahwa Google penuh dengan tim di mana setiap anggota memiliki peran ekstra sebagai manajer produk, di mana mereka tidak terlatih, tidak terkelola, dan diberi insentif untuk bekerja secara tidak efektif. Misalnya, teknisi Anda di tiket ini memprioritaskan bug yang dihadapi pengguna ini, yang merupakan pekerjaan manajemen produk.

@mleonhard - sekali lagi, saya mengerti ini adalah masalah yang membuat frustrasi, dan dapat menghargai bahwa bahasa yang berbeda memiliki fitur berbeda yang dapat membuat masalah ini lebih atau kurang serius. Karena itu, saya mendorong Anda untuk melihat kode etik Dart , yang memiliki harapan yang sama dengan kode etik Flutter .

Harap luangkan waktu untuk mempertimbangkan harapan tersebut, dan apakah Anda dapat terus berpartisipasi dalam diskusi ini.

@dnfield Saya minta maaf atas nada posting saya di sini. Saya akan berusaha untuk lebih hormat dan tidak terlalu agresif.

Untuk apa nilainya, di Chrome, dan mungkin browser lain, ada "kursor" tersembunyi (yang dapat Anda lihat jika Anda menekan F7) yang merupakan tempat pencarian dimulai. Jadi misalnya jika Anda mengklik paragraf pertama teks di halaman dokumen API, lalu tekan Ctrl+F, lalu cari, itu akan melewati hal-hal di kolom pertama.