Panduan suara dan nada

Berbagai orang termasuk Profesional TI dan pengembang membaca dokumen .NET baik untuk mempelajari .NET maupun menggunakannya dalam pekerjaan reguler mereka. Tujuan Anda adalah untuk membuat dokumentasi hebat yang membantu pembaca dalam perjalanan mereka. Pedoman kami membantu dengan itu. Panduan gaya kami berisi rekomendasi berikut:

Menggunakan nada percakapan

Paragraf berikut ditulis dalam gaya percakapan. Salah satu yang mengikutinya adalah dalam gaya yang lebih akademik.

Gaya yang sesuai

Kami ingin dokumentasi kami memiliki nada percakapan. Anda harus merasa seolah-olah Anda melakukan percakapan dengan penulis saat Anda membaca salah satu tutorial atau penjelasan kami. Bagi Anda, pengalaman tersebut harus informal, percakapan, dan informatif. Pembaca harus merasa seolah-olah mereka mendengarkan penulis menjelaskan konsep kepada mereka.

Gaya yang tidak pantas

Orang mungkin melihat kontras antara gaya percakapan dan gaya yang ditemukan dengan perawatan topik teknis yang lebih akademik. Sumber daya tersebut sangat berguna, tetapi penulis telah menulis artikel-artikel tersebut dengan gaya yang sangat berbeda dari dokumentasi kami. Ketika seseorang membaca jurnal akademik, seseorang menemukan nada yang sangat berbeda dan gaya penulisan yang sangat berbeda. Orang merasa bahwa mereka membaca akun kering dari topik yang sangat kering.

Tulis dengan orang kedua

Paragraf berikut menggunakan orang kedua. Yang mengikutinya menggunakan orang ketiga. Silakan tulis dengan orang kedua.

Gaya yang sesuai

Tulis artikel Anda seolah-olah Anda berbicara langsung dengan pembaca. Gunakan orang kedua sering (seperti dalam dua kalimat ini). Orang ke-2 tidak selalu berarti menggunakan kata 'Anda'. Tulis langsung ke pembaca. Tulis kalimat imperatif. Beri tahu pembaca apa yang Anda inginkan untuk dipelajari oleh mereka.

Gaya yang tidak pantas

Penulis juga dapat memilih untuk menulis dengan orang ketiga. Dalam model itu, penulis harus menemukan beberapa kata ganti atau kata benda untuk digunakan saat merujuk ke pembaca. Pembaca mungkin sering menemukan gaya orang ketiga ini kurang menarik dan kurang menyenangkan untuk dibaca.

Menggunakan suara aktif

Tulis artikel Anda dengan suara aktif. Suara aktif berarti bahwa subjek kalimat melakukan tindakan (kata kerja) kalimat tersebut. Kontras dengan suara pasif, di mana kalimat diatur sedemikian sehingga subjek kalimat ditindaklanjuti. Kontraskan dua contoh ini:

Compiler mengubah kode sumber menjadi executable.

Kode sumber diubah menjadi executable oleh pengkompilasi.

Kalimat pertama menggunakan suara aktif. Kalimat kedua ditulis dengan suara pasif. (Kedua kalimat tersebut memberikan contoh lain dari setiap gaya).

Kami merekomendasikan suara aktif karena lebih mudah dibaca. Suara pasif bisa lebih sulit dibaca.

Tulis untuk pembaca yang mungkin memiliki kosakata terbatas

Anda menjangkau audiens internasional dengan artikel Anda. Banyak pembaca Anda bukan penutur asli bahasa Inggris dan mungkin tidak memiliki kosakata bahasa Inggris yang Anda miliki.

Namun, Anda masih menulis untuk profesional teknis. Anda dapat berasumsi bahwa pembaca Anda memiliki pengetahuan pemrograman dan kosakata khusus untuk istilah pemrograman. Pemrograman Berorientasi Objek, Kelas dan Objek, Fungsi dan Metode adalah istilah yang familier. Namun, tidak semua orang membaca artikel Anda memiliki gelar ilmu komputer formal. Istilah seperti 'idempotent' mungkin perlu didefinisikan jika Anda menggunakannya, misalnya:

Metode Close() ini idempotensi, yang berarti Anda dapat memanggilnya beberapa kali dan efeknya sama seperti jika Anda memanggilnya sekali.

Hindari tegang di masa mendatang

Dalam beberapa bahasa non-Bahasa Inggris konsep tegang masa depan tidak sama dengan bahasa Inggris. Menggunakan tegang di masa mendatang dapat membuat dokumen Anda lebih sulit dibaca. Selain itu, saat menggunakan tegang di masa depan, pertanyaan yang jelas adalah kapan. Jadi, jika Anda mengatakan 'Learning PowerShell akan baik untuk Anda" - pertanyaan yang jelas untuk pembaca adalah kapan itu akan baik? Sebaliknya, katakan saja "Learning PowerShell baik untuk Anda".

Apa itu - jadi apa?

Setiap kali Anda memperkenalkan konsep baru kepada pembaca, tentukan konsep dan hanya kemudian jelaskan mengapa konsep tersebut berguna. Penting bagi pembaca untuk memahami apa sesuatu sebelum mereka dapat memahami manfaatnya (atau sebaliknya).