Bagaimana cara mendokumentasikan Bahasa yang Dapat Dideteksi?


14

Perusahaan kami sedang dalam proses mengubah banyak proses bisnis manual (dan pengetahuan institusional terkait) menjadi perangkat lunak perusahaan baru. Proyek ini berjalan dengan sangat baik, tetapi ketika kami melanjutkan jelas bahwa ada banyak kebingungan mengenai istilah dan definisi pada sisi bisnis dan pengembangan.

Saya telah mengetahui argumen Evan untuk membentuk bahasa di mana-mana untuk sementara waktu, tetapi ini adalah pertama kalinya saya perlu mendokumentasikannya secara formal. Ketika saya melihat sekeliling dan mencoba memikirkan di mana / bagaimana mendokumentasikan istilah UL kami, saya agak bingung.

Bagaimana perusahaan lain mendokumentasikan bahasa di mana-mana? Apakah ini hanya kamus bergaya wiki? Apakah ada alat yang dimaksudkan untuk tujuan ini?


1
Ini awal yang baik: thepaulrayner.com/blog/2013/05/07/… . Saya terutama menyukai bagian ini: "yang penting seharusnya bukan bahwa domain didokumentasikan, itu dipahami, dan bahwa pemahaman ini dibagi di antara semua orang yang terhubung dengan pengembangan perangkat lunak."
Robert Harvey

Wow - pertanyaan yang luar biasa. Jika saya memiliki pertanyaan ini, saya akan melihat ke EventStorming, dan melihat apakah ada cara yang masuk akal untuk mendokumentasikan hasil dari proses itu.
VoiceOfUnreason

Jawaban:


4

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) ".

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.