Anda dapat memperlakukan "dokumentasi bahasa yang ada di mana-mana" sebagai proyek penyesuaian perangkat lunak: Anda perlu mengambil beberapa perangkat lunak untuk manajemen dokumentasi dan menyesuaikannya dengan kebutuhan spesifik Anda. Dalam proyek perangkat lunak Anda biasanya mulai dengan mengumpulkan kebutuhan pengguna, kemudian Anda membangun arsitektur informasi dan solusi desain dan kemudian Anda melanjutkan ke implementasi. Di bawah ini adalah contoh dari proses ini.
Apa yang dibutuhkan pengguna untuk itu? Di beberapa organisasi, orang-orang dengan fungsi berbeda dari domain berbeda ingin menggunakan dialek bahasa umum untuk menjelaskan masalah dan solusi mereka. Dialek ini hanya akan ditentukan oleh kosa kata (kata-kata dan kiasan), karena pengucapan mungkin tidak penting di sini dan tata bahasa akan didasarkan pada bentuk sastra dari bahasa tersebut. Untuk mendokumentasikan dialek, Anda perlu merancang struktur dokumentasi yang paling cocok untuk mengelola kosakata (daftar istilah).
Orang mungkin ingin menggunakan dokumentasi ini untuk mempelajari arti kata atau akronim, untuk menemukan kata yang benar berdasarkan sinonim atau definisi atau untuk mempelajari semua kata yang menyusun domain.
Untuk kebutuhan pengguna ini, wiki memang merupakan pilihan yang baik. Bagaimana itu cocok? Dalam sistem wiki yang baik seperti Confluence atau MediaWiki dimungkinkan untuk:
- Buat artikel untuk setiap istilah.
- Tetapkan struktur umum artikel dalam beberapa templat, sehingga mereka akan berisi beberapa bagian umum, yang dapat digunakan untuk agregasi.
- Mudah menambahkan tautan ke definisi istilah di artikel wiki lainnya.
- Buat tabel agregat dengan definisi istilah dan tempelkan dalam dokumentasi lain.
Saat ini saya menggunakan Confluence untuk mendokumentasikan arsitektur informasi dan definisi bahasa di mana-mana adalah bagian dari itu. Level tertinggi dari dokumentasi ini adalah artikel domain. Dalam setiap aplikasi terdapat beberapa domain, mis. Keamanan, pembayaran, dll. Domain ini ditentukan oleh sejumlah interaksi pengguna dengan sistem, yang dapat dijelaskan melalui bahasa di mana-mana, jadi saya menempatkan definisi interaksi ini dalam subhalaman yang terpisah, dan definisi istilah yang diperkenalkan oleh interaksi ini di subhalaman halaman interaksi. Saya menempatkan tabel agregat pada halaman induk sehingga dimungkinkan untuk melihat, misalnya, skenario mana yang terdiri dari domain dan istilah mana yang didefinisikan di dalamnya.
Ketika struktur dokumentasi ini selesai dan saya pergi ke spesifikasi sistem yang lebih rinci, saya dapat merujuk definisi IA dan UL dari skenario, misalnya "komponen A mengimplementasikan integrasi dengan sistem B untuk mendukung interaksi C (tautan skenario IA) dengan menyampaikan informasi tentang Z (tautan UL) ".