Sekarang pembuat sepatu dengan sepatu bot, atau Bagaimana kami mendapat panduan gaya kami sendiri

Saya berasumsi bahwa, para pembaca yang budiman, dalam pekerjaan Anda, Anda harus berurusan dengan dokumentasi teknis dan, mungkin, bahkan dengan mereka yang membuatnya - dengan penulis teknis. Dan di blog kami, Anda bisa bertemu penulis teknis dari tim Veeam.

Hari ini kita beralih ke tingkat pemahaman selanjutnya tentang bagaimana pengembangan dokumentasi teknis dalam Perangkat Lunak Veeam bekerja.

KDPV menipu - ini bukan keajaiban, tetapi pekerjaan yang sama dengan semua rekan R&D lainnya. Namun, mereka yang membuat panduan memiliki kata-kata ajaib untuk panduan mereka dalam membuat panduan! Inilah rekursi semacam itu.

Baca lebih lanjut dalam kisah rekan saya Daria Shalygin.

Hai, nama saya Dasha dan saya adalah Lead Kualitas Konten di Veeam Software. Saya bertanggung jawab atas kualitas konten yang dibuat oleh departemen penulis teknis perusahaan kami. Dalam praktiknya, saya seorang penulis teknis dan editor dalam satu botol. Tanggung jawab saya meliputi:

• menjalankan proyek saya sendiri - seperti semua penulis teknis, saya memiliki bidang tanggung jawab saya, yaitu sejumlah produk yang saya buat dan kelola dokumentasi;
• pelatihan untuk karyawan tingkat junior - Saya membuat kursus pengantar untuk "pemula", yang saya habiskan untuk menjelaskan aturan dasar untuk menulis dokumentasi;
• memberi nasihat kepada karyawan di tingkat yang lebih tinggi (berpengalaman dan senior) - Saya memiliki jadwal harian yang dijadwalkan di mana setiap anggota tim kami dapat mengajukan pertanyaan apa pun mengenai dokumentasi (apakah itu kata, struktur, dll.);
• — , , , .

Hanya 3 tahun yang lalu kami hanya memiliki 8 penulis teknis. Ketika seseorang baru datang, ia mempelajari panduan yang ada dan mulai menulis dengan nada yang kira-kira sama. Itu adalah waktu yang indah ketika kita semua memiliki perasaan keindahan yang sama, dan kita dapat dengan mudah mencapai pemahaman umum tentang bagaimana menulis dokumentasi untuk produk kita.

Waktu berlalu, perusahaan tumbuh, ada lebih banyak produk, dan ada kebutuhan untuk menambah staf penulis teknis. Hari ini kami sudah 18 orang, dan kami tidak berencana untuk berhenti di situ. Semuanya akan baik-baik saja, tetapi tiba-tiba ternyata dengan begitu banyak orang menyepakati yang indah menjadi sulit. Butuh waktu, waktu, dan waktu lagi.

Untuk mengurangi biaya energi untuk mentransfer pengetahuan ke pendatang baru, serta untuk memperbaiki sekali dan untuk apa yang "indah" dalam dokumentasi teknis Veeam, diputuskan untuk membuat panduan gaya kami sendiri. Saya harus mengatakan bahwa beberapa sketsa pada tema gaya telah ada selama bertahun-tahun dalam bentuk artikel tentang Confluence dan catatan pinggir di notebook, tetapi semua ini tidak teratur, terfragmentasi, dan, tentu saja, untuk berbicara tentang kemudahan penggunaan dan relevansi informasi tidak harus.

Itu adalah:



Ketika kami menciptakan panduan gaya kami, kami mengambil sebagai dasar 3 panduan besar, yang biasanya diambil sebagai sampel ketika menulis dokumentasi: ( Chicago Manual of Style , Microsoft Manual of Style dan DITA Best Practices)), Mempelajari sejumlah panduan gaya pihak ketiga yang ada dengan perusahaan lain (misalnya, IBM Style Guide , Dokumentasi Gaya Panduan untuk OpenSolaris dan lain-lain), melakukan studi tren terbaru di bidang dokumentasi - dan dicampur semua ini dengan kita sendiri sebelas tahun pengalaman di Veeam Software.

Itu menjadi:



Sebagai hasilnya, Panduan Gaya Penulisan Teknis Veeam memasukkan topik-topik topikal seperti penataan konten berdasarkan jenis topik, prinsip-prinsip bahasa Inggris Polos, tanda baca, artikel, pemformatan, pembuatan screenshot dan diagram, membuat tautan ke dokumentasi Anda sendiri dan pihak ketiga, serta pengingat yang berguna untuk setiap hari.

Dengan munculnya panduan gaya, kami tidak hanya memfasilitasi proses transfer pengetahuan kepada karyawan baru, tetapi juga menerima keuntungan berikut:

• mencegah perlunya mencari reptil gaya pihak ketiga dan Internet untuk mendapatkan jawaban atas pertanyaan yang muncul secara teratur;
• resolusi instan dari masalah kontroversial mengenai bahasa, desain dan struktur dokumen;
• navigasi yang nyaman melalui basis pengetahuan Anda sendiri;
• kemampuan untuk menyediakan tautan ke bagian tertentu kepada kolega dari departemen lain yang secara langsung atau tidak langsung bekerja dengan menulis teks (apakah itu Dukungan atau QA).

Sebuah meme terkenal tentang bagaimana gaya penulisan berubah secara dramatis setelah Anda bekerja sebagai penulis teknis.

Panduan gaya kami dibuat oleh penutur non-asli (non-penutur asli) dan ditujukan untuk penutur non-penutur asli. Namun demikian, itu dibaca dan diverifikasi oleh penutur asli kami, ahli bahasa pemasaran yang memiliki pendidikan yang sesuai, telah lama menulis teks untuk situs web perusahaan, dan telah mengembangkan panduan gaya mereka sendiri, juga berdasarkan pada prinsip-prinsip raksasa yang disebutkan di atas. industri.

Kami saat ini sedang berupaya memperluas basis pengetahuan kami. Kami ingin membuat panduan gaya terpisah untuk dokumen referensi seperti REST API Reference dan PowerShell Reference. Untuk dokumen semacam itu, konten perlu disusun dengan cara khusus, dan ini perlu diperbaiki untuk menjaga keseragaman antar produk.

Kami akan senang jika panduan gaya kami akan berguna bagi perusahaan lain yang masih mencari gaya mereka sendiri. Saya menyarankan Anda untuk melihat bagian dengan informasi latar belakang , yang, dalam pengalaman kami, sering diperlukan dalam pekerjaan - ada banyak hal menarik. :)

Panduan Gaya Penulisan Teknis Veeam (Bahasa Inggris)