Meskipun pertemuan kedua Write the Docs Moscow terjadi sebulan yang lalu, tidak pernah terlambat untuk menerbitkan laporan dan abstrak singkat laporan. Kami berhasil mendiskusikan, dengan baik, hampir segalanya: dari mendokumentasikan API RESTful hingga lintasan profesional seorang penulis teknis.
Ngomong-ngomong, Mitap mengumpulkan tidak hanya "ghetto teknis", tetapi juga berbagai spesialis lain yang bekerja dalam satu atau lain cara dengan dokumentasi pada proyek: pemimpin tim, analis, penguji, dan bahkan satu direktur teknis.
Pertemuan kami
berlangsung pada 14 Oktober , Minggu (ia memasuki pertanyaan paling populer tentang dirinya, "Mengapa pada hari Minggu?") Di kantor IPONWEB. Demonstrasi Write the Docs diadakan di seluruh dunia dari Bangalore ke San Francisco, dari London ke Seoul, cabang komunitas Rusia hanya mendapatkan aktivitas, tetapi sudah ada cabang di Moskow, St. Petersburg, dan Novosibirsk.
Anton Telin, Mengapa dan bagaimana kami melakukan instruksi videoVideoSlideAnton mengelola departemen dokumentasi teknis di VLSI, yang membuat sistem manajemen dokumen elektronik. Kenapa harus video? Orang tidak mau membaca instruksi, mereka ingin menyelesaikan masalah. Orang ingin dijelaskan dengan jelas dan jelas kepada mereka.
Video adalah cara yang mudah untuk menyajikan sejumlah besar informasi, mengimplementasikan skrip dalam dinamika, serangkaian tindakan. Anda juga dapat menonjolkan perhatian pengguna dengan musik atau sulih suara.
Jika produk tersebut kompleks dan tidak memiliki antarmuka yang dipikirkan dengan matang, maka tanpa bagian visualnya sulit untuk menyampaikan esensinya kepada pengguna. Kelebihannya adalah mengurangi biaya dukungan teknis.
Kontra - tidak cocok untuk semua format publikasi, sulit untuk menanamkan dalam doc dan pdf. Sulit untuk mencarinya. Video berkualitas tinggi lebih mahal.
Masalah mendesak lainnya adalah kompleksitas pembaruan, tetapi kampanye Anton menyelesaikan masalah ini. Mereka menolak untuk merekam screencasts (tangkapan layar) demi tangkapan layar berkualitas tinggi.
Perusahaan menggunakan dua format video:
1. Instruksi video adalah urutan tindakan, secara terperinci dan dalam langkah-langkah. Durasi ~ 2 menit. 1 instruksi adalah 1 masalah. Itu tidak berbicara tentang semua jendela, gagak, tombol. Kemudian ditambahkan dubbing, musik latar, penjelasan teks, keterangan.
2. Video penjelasan. Ini adalah sesuatu di persimpangan instruksi dan presentasi produk. Pandangan umum tanpa detail teknis memecahkan beberapa masalah atau skenario. Video ini dapat mencakup orang dan animasi. Durasi 2-3 menit.
Alat: Adobe Premiere dan Adobe After Effect untuk mengedit, Adobe Audition untuk suara, Photoshop dan Snagit untuk mengedit gambar. Proyek ini dirakit dari berbagai tangkapan layar, yang tidak relevan atau salah maka mudah untuk diganti. Selanjutnya, menggambar gerakan mouse, animasi, suara.
Mereka memutuskan untuk menggunakan penyiar non-profesional untuk dubbing, karena mereka terdengar terlalu formal, sehingga mereka menggunakan suara seorang karyawan perusahaan, Ilya, yang bernyanyi dalam grup metalcore. Setelah blok informasi, jeda 2 detik untuk pemahaman perlu diberikan.
Video-video tersebut dipublikasikan di hosting Anda sendiri dan di Youtube. Downside memblokirnya oleh banyak perusahaan untuk alasan keamanan.
Tentu saja, VLSI mengumpulkan semua statistik yang tersedia: waktu menonton rata-rata, suka, panggilan dukungan teknis, yang ditutup menggunakan tautan video.
Nikolay Volynkin, Penulis teknis versi 2.0.1VideoSlideIni adalah pengulangan, atau lebih baik dikatakan, tambahan untuk laporan dari konferensi SECR. Nikolai memperhatikan penulis teknis untuk waktu yang lama dan memperhatikan bahwa mereka tidak selalu tahu bagaimana membenarkan dan mengukur manfaat mereka, dan para pemimpin yang mengatur tugas mereka juga.
Ada beberapa tugas terkait yang bisa diselesaikan oleh penulis teknis. Nikolay mengatakan lintasan karier dan keahlian apa yang memiliki deskripsi teknis, cara menjual tugas baru Anda ke bisnis.
5 peran yang bisa dimainkan oleh penulis teknis:
1.
Docops - devops untuk dokumentasi, penulis / programmer, ia dapat mengotomatiskan pembuatan, verifikasi, pengunggahan dokumentasi, melatih tim untuk bekerja dengannya dan membangun kembali semua proses di sekitarnya.
Keuntungannya adalah pengurangan tenaga kerja manual, penghematan sumber daya, dan kecepatan pengiriman fitur yang lebih tinggi.
2.
Penulis UX - spesialis menulis teks dalam antarmuka.
Manfaat - desainer, puisi, analis atau pengembang front-end tidak selalu mengerti cara menulis dengan benar, bagaimana menyampaikan fungsi, tombol, transisi ke pengguna. Teks ditulis sesuai dengan prinsip siapa yang pertama kali bangun dan sandal. Kenyamanan antarmuka, mengurangi waktu untuk dukungan teknis.
3. Seorang
penginjil teknis , ia berbicara tentang teknologi, berinteraksi dengan komunitas, membentuknya.
Manfaat - meningkatnya kepercayaan dan loyalitas kepada perusahaan, terhadap produk, penyederhanaan perekrutan, merek SDM.
4.
Knowledge Manager - mengeksplorasi cara perusahaan memproduksi, menyimpan, dan mentransfer pengetahuan. Tetapkan proses-proses ini agar pengetahuan tidak bocor.
Manfaat - faktor bus berkurang, kecepatan adaptasi karyawan, baik pemula maupun selama transisi di dalam, penggunaan kembali pengetahuan, pengurangan risiko.
5.
Pemilik Dokumentasi - PM dan analis dokumentasi. Ia membangun seluruh sistem komunikasi dan interaksi pengguna dalam dokumentasi.
Manfaatnya lagi dalam menurunkan biaya dukungan.
Selama diskusi, kami mengingat peran yang terintegrasi sebagai pengelola konten, yang tidak disebutkan dalam laporan.
Konstantin Valeev, FoliantVideoSlideConstantine dari Restrim berbicara tentang alat
Foliant - implementasi alur kerja docops berdasarkan bahasa penurunan harga. Setahun yang lalu, sebagai bagian dari
mini-Hyperbaton di Yandex, Konstantin sudah berbicara tentang Foliant, dan banyak yang telah berubah sejak saat itu.
Dokumentasi ini ditulis dalam file MD, dan berbaring di tempat yang berbeda, alat ini mendukung integrasi berkelanjutan, perakitan otomatis, dan juga memungkinkan Anda untuk memperluas MD sesuai keinginan Anda.
Persyaratan: Anda perlu memberikan docx untuk pelanggan dan PDF dengan tipografi yang baik, memiliki sumber yang dapat dibaca manusia (bukan XML).
Di bawah tenda, konverter Pandoc universal digunakan, Python, skrip bash terluka di atasnya. Tetapi seiring berjalannya waktu, jumlah skrip bertambah, sehingga mereka ditulis ulang menjadi satu aplikasi tunggal, monolitik.
Dari monolith, mereka kemudian membuat struktur modular dengan kernel yang mengendalikan perakitan, preprosesor yang mengubah MD untuk pekerjaan assembler, dan assembler itu sendiri.
Foliant pada dasarnya adalah perekat antara alat yang bagus (mkdoc, pandoc, slate, latex). Sekarang mereka berusaha mengajarkan cara mengonsumsi sumber dokumentasi dari berbagai format.
Dalam folder proyek ada konfigurasi dengan struktur dokumen akhir, gaya dan file MD yang sebenarnya, maka preprosesor mengambil sumber file MD dan menerapkan pemrosesan untuk mereka untuk membuat MD yang diinginkan dalam gaya all.md (md dalam gaya foliant), kemudian kolektor dokumen akhir ( pandoc, mkdoc) menjadikannya target (dokumen). Setelah perakitan MD, linter dijalankan untuk memeriksa sintaks. Pemberitahuan tentang build atau bug juga dikirim.
Semua ini dapat dikumpulkan di Docker, sehingga semua paket dikirim dengan satu cara, dan tidak masing-masing secara terpisah.
Foliant mendukung lanjutan termasuk, dapat mengekstrak potongan kode dari Gitlab / Github dan gambar dengan tata letak dari Simpli, dapat menggambar diagram, mengganti parameter dalam teks, pernyataan kondisional.
Nikita Samokhvalov, Dokumentasi komprehensif tentang RESTful APIVideoSlideNikita Samokhvalov, Direktur Teknis Notamed, mengatakan bagaimana mereka mengkonfigurasi generasi dokumentasi API berdasarkan Open API 3.0.
Seperti orang lain, mereka memulai dengan Google Documents, tetapi tidak memiliki versi atau kemampuan untuk membuat cabang. Kemudian mereka baru saja mulai menulis file MD di repositori, masalah versi dan pembuatan cabang diselesaikan, tetapi semuanya lambat. Kemudian datang ke generasi otomatis.
Dokumentasi memiliki persyaratan sebagai berikut: pewarisan dan penggunaan kembali potongan-potongan dokumentasi, kemampuan untuk memberikan tautan ke deskripsi parameter dan metode, informasi tentang diferensiasi hak akses, dokumentasi sebagai kode (penyebaran dan perubahan yang sinkron). Selain itu, dokumentasi tidak dipublikasikan untuk umum, hanya untuk tim Anda dan tim pengembangan lulusan.
Kami memilih spesifikasi OpenAPI 3.0. Mengapa Ini adalah yang paling segar, mendukung lebih banyak fitur, meskipun masih ada ekosistem kecil dan keahlian di sekitarnya.
Mereka mengambil alat
shins (menunjukkan file MD di halaman arahan yang indah dengan contoh-contoh pertanyaan, deskripsi metode, parameter),
widdershins (yaml / json ke MD converter), mereka juga menulis paket
specker mereka sendiri (menginstal semua dependensi yang diperlukan, bekerja melalui npm, juga memeriksa kebenaran struktur alokasi file).
Menyiapkan lingkungan dan merakit dokumentasi dilakukan pada satu baris di konsol. File yang perlu digunakan kembali di setiap proyek, misalnya, deskripsi otorisasi, jatuh ke dalam dependensi / folder.
Nikita juga berbicara tentang bagaimana mereka bekerja dengan cabang-cabang dalam tim terdistribusi, ketika tugasnya adalah memperbarui dokumentasi dan, tentu saja, tentang jebakan dan kesulitan yang menyertai implementasi OpenAPI 3.0.
Svetlana Novikova, Manajemen Pengetahuan Menggunakan Matriks KompetensiVideoSlideSvetlana (omong-omong, ini saya) berbicara tentang bagaimana mereka di perusahaan mengatur reboot instrumen end-to-end dari lingkup manajemen personel sebagai matriks kompetensi, apa gunanya manajemen pengetahuan dengan cara ini, bagaimana instrumen membantu mengurangi faktor bus, lebih baik naik ke pendatang baru, bahkan menemukan bagian-bagian baru kode untuk refactoring.
Danila Medvedev, NeuroCodeVideoDanila berbicara tentang alat yang dapat dimengerti oleh semua orang dan mungkin di masa depan, untuk memodelkan dan menyimpan pengetahuan yang disebut NeuroCode.
Alat ini bermanfaat bagi siapa pun yang terlibat dalam desain sistem TI. Secara khusus, Danila menyarankan untuk meninggalkan sistem berbasis dokumen. Sistem apa pun dianggap sebagai jaringan, sesuai dengan simpul di mana beberapa informasi dikirimkan. Semua elemen sistem mematuhi prinsip ini - pembaruan push, transfer dokumen, transfer umpan balik. Tujuan dari NeuroCode adalah "untuk mengurangi biaya tidak produktif untuk mendukung proses dan memperkuat kecerdasan kolektif organisasi".
Proyek NeuroCode tumbuh dari penyelesaian masalah - cara membuat repositori informasi yang baik untuk tim atau untuk Anda sendiri, cara membuat model informasi. Prototipe sistem dibuat dan berfungsi, sekarang sedang diuji dengan bantuan insinyur sistem dan arsitek bisnis. Sistem ini memiliki antarmuka yang dapat diskalakan dan didasarkan pada struktur data fraktal. Ini juga didasarkan pada ide-ide Douglas Engelbart (ini adalah salah satu peneliti pertama pada antarmuka manusia-mesin, penulis konsep GUI, hypertext, dll.) Tahun 1960-an tentang Open Hyper-Document Systems (OHS), ketika sistem tidak berbasis dokumen, tetapi satu Artinya, ia mengimplementasikan semua proses aktivitas manusia.
PS Secara umum, lebih baik menonton video.
Pertemuan berikutnya,
Write the Docs Moscow, akan berlangsung pada 7 Desember di kantor Positive Technologies, dan akan diadakan dalam format Positive Authoring Tools Battle.
