sistem dokumentasi teknis online seperti apa yang akan Anda rekomendasikan? [Tutup]

tujuannya adalah untuk memiliki sistem dokumentasi online, dengan persyaratan utama ini:

akan terutama digunakan sebagai tahap perantara untuk dokumen teknis akhir dari semua aplikasi kita (yang mungkin tidak akan pernah selesai:)). Biasanya akan digunakan sebagai berikut: seseorang memiliki masalah, saya memperbaikinya, dan menuliskan perbaikannya segera. Apa yang terjadi sekarang semakin tidak dapat dikelola: seseorang memiliki masalah, saya memperbaikinya, saya dan seseorang bahagia tetapi 2 bulan kemudian orang lain memiliki masalah yang sama dan tidak ada yang ingat apa yang diperbaiki.
dapat diakses dari mana saja, berjalan di belakang server apache kami
manajemen pengguna / grup, memungkinkan akses hanya baca / baca-tulis / admin
formatnya tidak terlalu penting: teks biasa, gaya wiki akan lebih baik
murah atau gratis

beberapa ide saya:

hanya melayani file pada file sharing atau melalui ssh (kontra: tidak terlalu cocok dengan windows, pro: sederhana, bisa jenis file apa saja)
simpan di SCM (svn / git, idem seperti di atas tetapi lebih mudah untuk mengakses dan mengontrol akses)
Confluence: kita sudah menggunakan Jira, apakah Confluence layak? Bagaimana cara mengintegrasikan dengan Jira?
sesuatu yang lain?

Tolong jangan ragu mengomentari ini atau berbagi pengalaman Anda dengan sistem lain.

documentation stijn
sumber

Apakah dokumentasi dihasilkan dari kode (seperti Javadocs) atau apakah ditulis dari awal, sebagai panduan pengguna, atau kombinasi keduanya?

FrustratedWithFormsDesigner

ini terutama lebih dari panduan pengguna, bukan dokumentasi kode (well, kami memiliki itu juga, yang dihasilkan oleh doxygen, kami mungkin memasukkannya, tapi itu bukan poin pertama yang menarik)

stijn

Saya akan menyerahkan sejumlah uang kepada Spolsky.

Pekerjaan

Jawaban:

Saya akan menyarankan Wiki

Karena Confluence adalah wiki, saya pikir menggunakannya dengan JIRA Anda adalah ide yang bagus. Anda akan memiliki keuntungan untuk dapat secara langsung mengikat kembali ke masalah JIRA, dan oleh karena itu kode aktual / doc / perubahan apa pun yang dibuat dll.

Kunci untuk setiap repo kode dokumen seperti ini adalah aspek navigasi. Anda tidak ingin halaman yang terputus, sulit ditemukan dll. Pertimbangkan 'tata letak situs' seperti yang Anda inginkan untuk situs web.

Martijn Verburg
sumber

Pertemuan tampaknya dapat mengekspor dalam berbagai format datar. Suara seperti salah satu cara termudah untuk mendapatkan dari mudah dapat diedit untuk selesai produc.t

Kami memiliki Confluence tempat saya bekerja — kami bermigrasi dari MediaWiki — dan ini menghasilkan pekerjaan yang baik dengan sejumlah format (Word menjadi yang paling populer). Tetapi berhati-hatilah karena alat pengeditan WYSIWYG-nya sangat buggy dan sistem penandaan membuat banyak yang harus diinginkan, setidaknya pada instalasi kami.

Philip Regan

+1 untuk Wiki, saya juga menemukan Trac sangat berguna dalam kasus itu karena terintegrasi dengan SVN yang memungkinkan berbagi file juga.

kami memeriksa percobaan Confluence, dan itu akan menjadi solusinya. Tampaknya bisa melakukan jauh lebih banyak dari yang kita butuhkan, tetapi cukup mudah untuk dikerjakan. Saya mencoba Trac beberapa tahun yang lalu dan rasanya agak terlalu berantakan menurut selera saya, terutama ketika menyangkut plugins, dll.

stijn