Bagaimana Anda mendokumentasikan pekerjaan, proses, dan lingkungan Anda?

48

Apakah Anda menggunakan format wiki? Jika ya, produk apa? (MediaWiki, Confluence, Sharepoint dll.)

Sudahkah Anda membuat basis pengetahuan? (Dokumen pendek berorientasi masalah / solusi.)

Apa tantangan yang Anda temukan dengan membuat dokumentasi yang berfungsi, sehingga Anda tidak mendapat telepon saat Anda sedang berlibur?

Bagi saya, saya menemukan sering ada sejumlah "kelembaman" organisasi tertentu yang terlibat dalam menyelesaikan dokumentasi. Tampaknya ada jenis orang yang berbeda yang dapat melakukan tugas, kemudian berpikir tentang bagaimana mereka melakukan tugas itu dan menggambarkannya sehingga orang lain dapat melakukannya - jenis kekuatan untuk Anda "pergi meta" dan tidak semua orang merasa nyaman melakukan itu.

Memperbarui

Jawaban sejauh ini termasuk

  • Pertemuan
  • Flexwiki
  • Fogbugz
  • Mediawiki (dengan plugin seperti fckeditor)
  • Sharepoint
  • TWiki
  • Word / Excel / Visio Documents
  • Script yang Didokumentasikan

Sunting: Tidakkah Anda secara implisit mendokumentasikan jaringan Anda dengan sistem pemantauan? Nagios selalu mendorong penggunaan arahan orang tua untuk mencerminkan struktur jaringan Anda, dan direktif notes_url dirancang untuk memungkinkan Anda menautkan ke wiki atau dokumentasi berbasis browser lainnya. Jadi di sini "dokumentasi" dibagi antara "dokumen hidup" dari sistem pemantauan dan dokumentasi offline yang lebih terperinci dalam wiki. Karena saya menghabiskan banyak waktu menatap Nagios, masuk akal untuk berupaya se informatif mungkin.

Andrew H
sumber
pertanyaan Anda baru saja membuat slashdot tech.slashdot.org/article.pl?sid=09/05/25/2154237
nama pengguna
hehe :) Saya berharap saya entah bagaimana bisa menyimpulkan pertanyaan ini, mungkin menunggu beta untuk berakhir ...
Cawflands
Lihat bagian "terkait" di bilah sisi - serverfault.com/questions/3970/… mungkin yang Anda cari
Olaf
Sistem pemantauan seperti Nagios memberi tahu Anda seperti apa jaringan / sistem Anda saat ini. Mereka biasanya tidak memberi tahu Anda mengapa jaringan dan sistem diatur sebagaimana adanya.
David

Jawaban:

8

Mengomentari perkakas.

Kami sudah mencoba wiki online tetapi menemukan sejumlah batasan, yang mungkin sesuai selera pribadi, tetapi termasuk struktur dokumen dan yang paling penting harus terhubung ke server dokumentasi.

Terkoneksi adalah masalah serius jika Anda offline atau onsite (jelas Anda dapat mengurangi onsite dengan koneksi SSL aman dan lain-lain.)

Proses dokumentasi kami saat ini adalah:

  • generator html statis
  • sintaks penurunan harga
  • sistem versi terdistribusi

Kami memiliki tata letak 'formal' untuk dokumentasi dan yang menyediakan struktur untuk menu (dan CSS terkait untuk penataan visual dll.)

Generator HTML Statis

Kami menggunakan generator html statis in-house berdasarkan cubictemp dan sejumlah alat lain: pygments , docutils .

Halaman yang dihasilkan (tidak?) Jelas terlihat jelek, karena sebagian besar dari kita / sysadmin / programmer kita tahu apa yang indah secara estetika tetapi memiliki total kurangnya koordinasi dalam membangun seperti itu.

Tapi itu memberi / mari kita sertakan file konfigurasi, skrip sampel, pdf, dll, tanpa harus khawatir tentang format html mengacaukannya atau khawatir tentang di mana menemukannya di 'server' untuk mengunduh.

Jika bukan HTML, cukup taruh di folder dan tambahkan tautan url ke sana.

HTML menyediakan struktur 'potensial' untuk tata letak, dan juga secara kritis menyediakan 'tautan' antara item pengetahuan / konten (serta mekanisme struktur dasar, seperti mampu membuat menu, daftar isi, dll.) Dengan HTML, setiap pengguna kini dapat menjalankan server web kecil di mesin mereka apakah lighttpd atau sesuatu yang kecil atau hanya penuh dengan Apache atau IIS.

Semua mesin kami memiliki gerutuan untuk melayani html dasar, dan bekerja cukup baik untuk kami.

Sintaks MARKDOWN.

Kami menggunakan MARKDOWN, Textish, atau atau reStructuredTEXT versi bastardised untuk membiarkan jus 'kreatif' kami menulis dokumentasi tanpa harus khawatir tentang HTML.

Ini juga berarti setiap orang dapat menggunakan editor favorit mereka (saya menggunakan Scintilla pada Windows dan * Nix) sementara yang lain di sini menggunakan vi / vim.

Sistem Versi Terdistribusi.

Kami menggunakan Git untuk 'mendistribusikan' dokumentasi antara pengguna. Oh, dan kami menggunakan kapasitas versinya juga.

Keuntungan utama bagi kami adalah bahwa kita semua dapat bekerja memperbarui dokumentasi tanpa harus terhubung ke server, dan tanpa harus menerbitkan karya 'selesai'. Kita semua dapat mengerjakan bagian yang sama dari dokumentasi, atau bagian yang berbeda, atau hanya mengkonsumsi informasi.

Secara pribadi, saya benci diikat ke server untuk memperbarui blog apalagi wiki. Git bekerja dengan baik untuk kita.

Mengomentari Alur Kerja

Wiki tampaknya menjadi "mode" untuk penyebaran / kodifikasi pengetahuan, tetapi seperti dikomentari di tempat lain semua proses menjadi sulit untuk dipertahankan, dan menemukan campuran alat yang paling mendukung kebutuhan tim Anda dan berkelanjutan akan membutuhkan waktu.

Solusi yang lebih baik akhirnya ditemukan dan tidak diamanatkan.

samt
sumber
1
Saya menggunakan ikiwiki di atas git. Juga memberi saya operasi penurunan harga dan terputus
ptman
7

Kami sudah mulai menggunakan DokuWiki tempat saya bekerja.

Dari situs web Dokuwiki:

DokuWiki adalah standar yang sesuai, mudah digunakan Wiki, terutama ditujukan untuk membuat dokumentasi apa pun. Ini ditargetkan pada tim pengembang, kelompok kerja dan perusahaan kecil. Ini memiliki sintaks yang sederhana namun kuat yang memastikan file data tetap dapat dibaca di luar Wiki dan memudahkan pembuatan teks terstruktur. Semua data disimpan dalam file teks biasa - tidak diperlukan database.

Saya menemukan Dokuwiki yang paling mudah diimplementasikan karena tidak memerlukan basis data, dan itu mudah diatur. Ada juga modul tambahan yang memungkinkan saya untuk menggunakan log masuk akun Direktori Aktif saya yang ada daripada harus membuat akun untuk semua orang, yang merupakan nilai tambah besar dibandingkan banyak sistem wiki lain yang saya temukan. itu juga memiliki kontrol versi khas, di mana Anda dapat melihat siapa yang diposting di mana, dan memiliki kemampuan untuk memutar kembali ke versi sebelumnya dengan mudah jika perlu. Mereka juga menyertakan beranda yang dapat disesuaikan yang mana Anda dapat dengan mudah mengubah jenis konten apa pun yang paling cocok untuk lingkungan Anda.

mrTomahawk
sumber
6

Doku Wiki atau Sharepoint untuk hal-hal lain yang masuk dalam bagan.

Anda terbiasa dengan cepat memposting di wiki dan sintaksisnya tidak terlalu rumit. Sangat mudah untuk mengatur informasi dan membuatnya mudah ditemukan nanti oleh orang lain.

Saya menggunakan visio untuk membuat grafik untuk penjelasan yang lebih jelas (ekspor sebagai JPEG).

Antoine Benkemoun
sumber
6

Kami menggunakan wiki. Faktanya, kami menggunakan MediaWiki. Di atas MediaWiki, kami memiliki ekstensi Semantic Mediawiki yang diinstal, yang sebenarnya mengubah MediaWiki kami menjadi sesuatu dari database yang diketik secara longgar yang dapat kami kueri dengan Kategori, judul, konten, dll.

Sebagai contoh, katakanlah saya ingin melihat semua cnames jaringan yang merutekan melalui Cluster F. Yang perlu saya lakukan adalah menggunakan halaman Special: Ask untuk meminta [[Kategori: cname]] [[destination :: cluster_f]] .. dan itu akan mengembalikan semua halaman yang dikategorikan sebagai cname dengan tujuan sebagai cluster_f.

Kami mendukung beberapa ratus pelanggan yang sangat berbeda, sehingga memiliki dokumentasi di tempat sentral (dan menghubungkannya sehingga kasus khusus tetap didokumentasikan dan diikat menjadi keseluruhan) adalah hal yang sangat berguna. Jelas, dokumentasi kami perlu dipertahankan, tetapi Anda dapat mengambil lebih banyak pendekatan 'tukang kebun' untuk pemeliharaan karena mediawiki toolkit untuk menjaga arus dataset besar sudah cukup matang.

Karl Katzke
sumber
6

Dengan plugin yang tepat, Trac dapat menjadi tiket kombinasi dan sistem wiki. Ini memudahkan tiket Anda untuk terhubung ke artikel wiki dan sebaliknya.

Beberapa plugin yang saya suka:

  • Plugin Tiket Pribadi . Trac dibangun sebagai bugbase di mana semua tiket dan tanggapannya bersifat publik. Itu tidak sesuai dengan sistem tiket TI, tetapi plugin ini memperbaikinya.
  • Plugin Trac WYSIWYG . Mari kita hadapi itu, kebanyakan orang tidak akan belajar wikisyntax untuk membuat Anda bahagia. Ini memberi mereka editor 'apa yang Anda lihat adalah apa yang Anda dapatkan' untuk halaman tiket dan halaman wiki.

Ada beberapa penyesuaian lainnya untuk Trac. Tidak sulit untuk mengatur dan menyesuaikan sistem Trac sesuai keinginan Anda!

quux
sumber
1
Beri ini +1. Wiki Trac tidak hanya memudahkan pembacaan dan pengeditan untuk dokumentasi. Saat digunakan dengan penerbitan tiket dan SVN untuk versi konfigurasi, Anda memiliki visibilitas yang mulus dari seluruh alur kerja.
Dan Carley
5

Dalam pekerjaan saya sebelumnya saya menggunakan Twiki. Itu bekerja dengan cukup baik.

Di samping itu, saya cenderung mengotomatiskan sebagian besar tugas, dan mendokumentasikan skrip (tidak selalu dengan banyak antusiasme, tapi tetap saja ...). Mendokumentasikan skrip mudah dilakukan dalam proses mendesainnya, jadi tidak ada overhead nyata ...

Kombinasi keduanya (dan menggunakan kontrol versi untuk skrip) melakukan trik dengan cukup baik.

Vincent De Baere
sumber
5

Gabungan dokumen JIRA, Confluence dan Word.

Andrew
sumber
5

Melembagakan Pengetahuan

Kami mulai dengan dokumen. Lalu kami menyimpannya di perpustakaan Sharepoint. Kemudian baru-baru ini kami pindah ke wiki Sharepoint. Saya suka pendekatan rendah-gesekan wiki dalam memperbarui hal-hal dengan cepat, meskipun wiki Sharepoint meninggalkan beberapa hal yang diinginkan dalam dukungan grafis dan dukungan format untuk hal-hal seperti tabel. Tidak masalah untuk teks dan editor internal memungkinkan beberapa pemformatan HTML dasar dan daftar berurutan / tidak berurutan. Ada alternatif murah lainnya untuk Sharepoint.

Kami juga memiliki semacam basis pengetahuan informal untuk tiket dukungan kami di perangkat lunak help desk kami, Track-It Numara. Itu tidak sempurna tetapi berhasil.

Mendapatkan Staf untuk Menggunakan Pengetahuan yang dilembagakan

Saya setuju dengan penilaian Anda bahwa mendapatkan pengetahuan yang dilembagakan hanyalah satu bagian dari pertempuran. Jika organisasi dan orang-orang Anda tidak terbiasa dengan "penelitian pertama, tanyakan yang kedua" maka Anda akan menemukan bahwa cara lama berlaku: semua orang akan tetap mencari jawaban guru formal dan informal, dan bagi sebagian orang akan selalu lebih mudah untuk bertanya orang di sebelah Anda daripada mencari sendiri.

Berurusan dengan ini akan melibatkan beberapa manajemen perubahan; seperti kebanyakan inisiatif perubahan sukses yang memengaruhi lebih dari sekadar tim kecil, ini akan membantu untuk mendapatkan dukungan dan dukungan manajerial. Anda benar-benar harus memalsukan perilaku baru dalam dua arah; seseorang perlu menangkap pengetahuan dan orang perlu menggunakannya. Lebih sulit lagi adalah bahwa orang juga perlu menjaga agar data tetap terkini.

Hanya beberapa ide: mungkin perlu ada dorongan dalam bentuk kebijakan formal yang menyatakan bahwa tiket dan masalah yang diselesaikan perlu didokumentasikan dalam basis pengetahuan atau wiki sebelum dapat dianggap ditutup. Selain itu, para pemimpin pengetahuan yang biasanya ditanyakan tidak seharusnya selalu hanya menawarkan jawaban atas permintaan; mereka perlu mengarahkan orang ke wiki dan membuat mereka terbiasa memeriksa di sana terlebih dahulu. Hal lain adalah membuat data tersedia bagi pengguna untuk swadaya sehingga masalah ini berpotensi diselesaikan sebelum menjadi item lain yang harus ditangani oleh staf teknis.

Apa yang menyenangkan adalah sistem help desk kami memiliki sistem yang mirip dengan StackOverflow dan ServerFault: ketika mengetik pertanyaan, mesin pencari menemukan item serupa dan menawarkannya, sehingga pengguna dapat melihatnya bahkan sebelum mengirimkan pertanyaan.

Bernard Dy
sumber
+1: Di mana saya bekerja, itu adalah masalah yang sama dengan membuat staf menggunakan sumber daya meskipun, khususnya, itu menggunakan sistem pelacakan masalah untuk melihat masalah. Saya akhirnya membawa orang-orang yang kesulitan mengubah kebiasaan mereka mengganggu saya kembali ke meja saya beberapa kali pertama dan mengisi tiket bug baru dengan mereka. Butuh waktu 2 bulan dan sekarang semua orang memasukkan bug mereka sendiri dan mereka semua dirawat. Pendekatan serupa mungkin berguna di sini (mis. Mencari dokumen yang dipermasalahkan dalam [sistem] dengan mereka)
Steven Evers
4

Di dua tempat kerja terakhir saya, saya menggunakan Sharepoint's Wiki, bersama dengan pustaka dokumen yang berisi dokumen-dokumen tertentu (seperti DRPs dan rencana upgrade satu kali) yang tidak dapat dengan mudah dibuat sebagai dokumen Wiki. Dokumen-dokumen itu memiliki tautan dari dalam Wiki. Wiki memiliki banyak keuntungan di bidang ini, karena banyak orang dapat mengeditnya, membuat versi bawaan, mudah dicari dan dapat diakses, dll. Untuk dengan cepat menulis catatan atau ide, saya akan menggunakan OneNote atau papan tulis.

Saya telah membuat beberapa basis pengetahuan sebelumnya, dalam format forum (baik dalam Lotus Notes dan MS Sharepoint), tetapi saya harus mengatakan bahwa jarang orang mencari melalui mereka untuk melihat apakah masalah tertentu sudah diselesaikan. Solusi seperti itu harus datang dari hari pertama dengan mesin pencari yang sangat kuat dan efektif.

Jika Anda ingin membuat dokumen yang dapat digunakan saat Anda sedang liburan, tulislah seolah-olah Anda sedang mencoba mengajar salah satu orang tua Anda. Ini bukan 100% pembodohan, tetapi terkadang membantu. Tergantung siapa yang membacanya.

Moshe
sumber
Saya setuju bahwa pencarian yang baik sangat penting untuk penggunaan alat-alat ini. Mendapatkan pencarian yang layak ke Sharepoint baru-baru ini dicapai oleh seorang kolega, tidak apa-apa tapi itu bukan Google.
Cawflands
4

Sharepoint itu bagus.

Fitur pencariannya memiliki kemampuan untuk mengindeks hampir semua jenis dokumen, membuat pencarian dokumentasi sangat mudah.

Ini dapat melakukan beberapa templating juga yang dapat membuat segalanya lebih mudah jika misalnya Anda memiliki lembar info standar untuk setiap server yang Anda buat.

Ini juga dapat membuat versi dokumen untuk Anda sehingga Anda memiliki riwayat audit perubahan dokumentasi.

Plus file yang terkandung dalam pustaka dokumen dapat diakses melalui web, dalam pandangan, atau melalui berbagi tanpa hak semua di luar kotak.

Dominic D
sumber
3

Kami telah menggunakan MediaWiki (dengan fckeditor) selama beberapa tahun, meskipun saya harus mengatakan akan lebih baik jika penanganan gambar (yaitu tangkapan layar) lebih mudah. Dan walaupun memiliki kemampuan untuk mencari sangat penting - saya menemukan pencarian MediaWiki sering kali melewatkan halaman. Mungkin itu hanya masalah belajar mencari yang lebih baik (yang mengalahkan tujuan memiliki cara sederhana bagi orang lain untuk melakukan pekerjaan Anda)

Saat ini kami sedang dalam pembicaraan tentang memindahkan semuanya ke MS Sharepoint , meskipun tidak perlu ke wiki mereka. Saya pikir Sharepoint dapat melakukan pencarian dokumen lengkap dengan cara yang meniadakan beberapa keunggulan wiki, jadi kita akan melihat ke mana perginya.

(tidak menantikan proses porting semua dokumentasi kami saat ini :))

Brent
sumber
1
Saya telah membaca bahwa Sphinx adalah tambahan yang layak untuk instalasi MW, untuk meningkatkan pencarian.
Cawflands
3

Kami menggunakan wiki. Tentu sintaks butuh sedikit untuk membiasakan diri, tetapi yang kita gunakan (twiki) menyimpan datanya sepenuhnya sebagai file teks. Ini memungkinkan kita untuk dengan mudah membacanya jika terjadi bencana, karena kita dapat mengembalikannya ke mana saja, dan mencari mereka dari baris perintah melalui grep, dan membacanya di editor teks yang kita suka.

Setiap server memiliki halaman, dengan koleksi standar sub-halaman untuk informasi manajemen perubahan, startup / shutdown, dan catatan konfigurasi, serta dns, firewall, dan info aset.

Laura Thomas
sumber
2

Kami sedang bersiap-siap untuk pindah ke beberapa versi layanan Sharepoint untuk mencoba mengeluarkan kami dari campuran dokumen kata yang tersebar di tiga server dan siapa yang tahu berapa banyak folder. Saat ini, kami memiliki spreadsheet excel besar yang berisi hyperlink ke dokumen yang dijelaskan di dalamnya.

Bukan cara terbaik untuk melakukannya, tetapi ketika perusahaan mulai, mereka tidak pernah merencanakan bagaimana menangani dokumentasi internal dan menyerahkannya kepada masing-masing kelompok untuk memutuskan bagaimana menyortir dan menyimpan dokumentasi mereka sendiri sesuai keinginan mereka. Sekarang, kami mencoba untuk bergabung ke dalam sistem terpadu, yang akan ada di sekitar salah satu penawaran Sharepoint.

pengguna41811
sumber
2

Di LSM tempat saya bekerja, kami hanya menggunakan file teks yang ditempatkan di folder untuk prosedur kritis. Secara pribadi sebagai Sistem Administrator / Pengembang Web hibrida saya telah menggunakan basis pengetahuan file teks yang tersebar di direktori pohon, itu Memex saya dan saya menuliskan hampir semua yang ada di dalamnya (pribadi, pekerjaan, dll). Skema ini sangat mudah dikelola menggunakan Jedit pisau tentara swiss nyata untuk pemrosesan teks, saya telah menemukan garis besarnya plug-in, kode lipat dan fitur hypersearch sangat diperlukan. Semua ini didukung dengan aman oleh rsync ke server jauh ssh-accesible.

teks alternatif

Berpasangan dengan Makelink Firefox Extension dan Anda memiliki pengelola bookmark yang sempurna.

cgomezsilva
sumber
1

Kami menggunakan flexwiki , yang merupakan dotnet dan open source.

James Moore
sumber
1

Erm ... bagaimana dengan Fogbugz? :)

Chopper3
sumber
1

Kami menggunakan ScrewTurn untuk konten dan SharePoint untuk menyimpan dokumen / gambar.

Jeff
sumber
1

Ada beberapa hal menarik di sini - saya suka yang tentang kata sandi di brankas.

Praha Sangha
sumber
1

Kami menggunakan kombinasi file teks untuk pencarian cepat dengan grep. Dan SharePoint untuk koleksi dokumentasi mendalam yang lebih terorganisir (diagram Visio, dll.).

TCampbell
sumber
1

Sebagai Google Apps (Enterprise) klien, kami menggunakan heck out dari Google Sites - "rasa" wiki mereka. Mudah digunakan dan kami memiliki adopsi yang bagus dari admin dan pengembang.

Chris_K
sumber
1

Saya tidak melihat pertanyaan ini sebelum menjawab pertanyaan lain , tapi ini dia.

Kami menggunakan sejumlah alat dan metode.

  • Spesifikasi fungsional untuk komponen infrastruktur dan perangkat lunak.
  • Dua Wikimedia Confluence . Satu untuk dokumentasi internal perusahaan (kebijakan, prosedur, infrastruktur internal dan TI, dll) dan satu untuk produk perangkat lunak sumber terbuka kami.
  • Tes RSpec dan Mentimun . Perangkat lunak kami sebagian besar ditulis dalam Ruby, dan kami berlatih BDD / TDD , jadi tes spesifikasi mendorong kode aktual, dan mendokumentasikan juga.
  • Dokumentasi kode sebaris. Kami menggunakan markah RDoc dalam komentar kode.
  • Manajemen konfigurasi deklaratif ( Chef ). Semua server kami dikelola dengan Chef, yang "mendokumentasikan sendiri" melalui sumber daya delcaratif dalam resep dan buku resep.

Kami menyukai Confluence karena sangat fleksibel dan kuat serta fitur lengkap, ditambah lagi dengan perangkat lunak manajemen tiket yang kami sukai, Jira .

Di perusahaan sebelumnya saya pernah bekerja, saya telah menggunakan berbagai alat dan metode dan banyak yang telah mencoba untuk tetap dengan satu sumber daya catch-all (seperti Wiki) untuk semuanya. Masalah dengan itu adalah mendokumentasikan berbagai topik dengan satu alat yang tidak secara unik cocok untuk membahas topik itu berarti bahwa banyak hal tidak akan didokumentasikan sama sekali, karena sulit untuk melakukan migrasi informasi. Sebagai geek Unix / Linux, saya percaya bahwa setiap tugas memerlukan alat khusus, dan alat itu harus sesuai dengan tugas itu dengan sangat baik.

jtimberman
sumber
1

Pertanyaan ini adalah duplikat yang sangat baik dari pertanyaan ini dan saya memindahkan jawaban saya di sana.

jtimberman
sumber
1

Saya melakukan sebagian besar dokumentasi untuk perusahaan saya, dan format yang dibuat ketika saya mulai bekerja di sini adalah MS Word untuk dokumen asli yang dapat diedit, diekspor ke PDF untuk rilis umum hanya-baca. Ini bekerja cukup baik untuk proyek-proyek di mana hanya satu orang memperbarui dokumen, dan karena orang itu biasanya saya, manajemen belum melihat kebutuhan untuk berubah.

Kami telah mulai mendokumentasikan bug kami dan tugas yang akan datang dengan Trac , sambil menggunakan ekstensi "Peer Review" untuk ulasan kode. Itu mendapat sambutan yang luar biasa dari tim kami karena mudah untuk berkolaborasi dan mudah dinavigasi. Beberapa anggota tim lain telah menyatakan keinginan untuk mulai berkolaborasi lebih banyak dengan spesifikasi, prosedur pengujian, dan manual, jadi kami melihat ke dalam DocBook / XML yang diekspor ke PDF untuk dokumentasi publik seperti manual, dan halaman Trac WIKI untuk dokumen internal seperti spesifikasi dan prosedur pengujian.

Menurut saya, masalah terbesar ketika memilih format dokumentasi adalah:

  1. Apakah mudah dibuat?
  2. Apakah mudah dirawat?
  3. Apakah mudah mempertahankannya jika orang lain yang menulisnya?
  4. Bisakah itu diekspor / dikonversi ke format lain tanpa banyak kesulitan?

1-3 membuat hidup saya lebih mudah, dan penting untuk menghasilkan dokumentasi dengan cepat tanpa menjadi gila. Saya pikir yang keempat adalah yang paling penting di sisi pelanggan, karena format akan terus berubah. Format Microsoft Word 2003 tidak akan ada selamanya, dan begitu juga implementasi PDF kami saat ini. Saya perlu memastikan bahwa semua pelanggan kami dapat membaca dokumen kami, apa pun OS atau pembaca dokumen pilihan mereka.

andrewd18
sumber
1

Kami menggunakan MediaWiki dengan berbagai plugin, termasuk SemanticMediaWiki. SMW bagus karena mengubah instalasi MediaWiki kami menjadi basis data relasional bentuk-bebas yang besar yang dapat ditanyakan sesuka hati. Perlu tahu di server mana situs web aktif? Kunjungi halamannya. Perlu tahu situs web apa yang dihosting di server? Jalankan kueri, dan itu akan memilih nama halaman berdasarkan tag yang tepat pada setiap halaman situs web.

Karl Katzke
sumber
1

Saya akan menjawab bukan dengan sistem dokumentasi yang saya gunakan, tetapi dengan sesuatu yang saya lihat digunakan dan yang saya temukan sangat baik: http://stackexchange.com/

stackexchange adalah platform T&J yang berjalan di bawah serverfault (well, secara teknis itu tidak persis sama, tetapi untuk tujuan kita di sini kita dapat menganggap itu sama).

Fogbugz menggunakannya .

Ada posting blog yang menarik dari seorang karyawan Fogbugz tempat saya menemukan kutipan ini:

Untuk semua tujuan di luar spesifikasi produk, saya pikir wiki perusahaan dan bentuk diskusi telah menjadi pukulan fatal.

...

Sejak kami mulai menggunakan FogBugz.StackExchange.com sebagai platform dukungan kami, saya tidak pernah menjawab pertanyaan yang sama dua kali. Kami bahkan memiliki server SE internal yang kami gunakan untuk tanya jawab yang tidak menghadap publik, dan prinsip yang sama berlaku di sana.

Mereka menggunakan stackexchange untuk basis pengetahuan yang dihadapi pelanggan dan basis pengetahuan internal.

Saya tertarik untuk melihat apakah platform tanya jawab pertukaran pengetahuan seperti itu akan menggantikan wiki perusahaan.

Steven
sumber
0

Di perusahaan saya sebelumnya, saya menggunakan file Word, Excel, dan Visio yang dikumpulkan bersama dalam satu folder. Salinan semuanya disimpan di map di mejaku. Saya adalah satu-satunya orang IT sehingga ada sedikit kebutuhan bagi orang lain untuk memiliki akses ke informasi.

Di perusahaan saya saat ini, kami menggunakan Macola ES oleh Exact Software, tapi saya masih lebih suka menulis dokumentasi saya di Word dan mengunggahnya ke Macola sebagai lampiran daripada menggunakan editor dokumen bawaan.

Scott
sumber
0

Di tempat kerja saya, saya menjatuhkan ScrewTurn Wiki di salah satu server dev Windows kami dan menghubungkannya ke SQL Server kami. Ini bekerja dengan sangat baik, berjalan dengan cepat, dan terutama tetap berada di luar cara kami untuk dokumentasi. Dalam dua minggu sejak disebarkan, kami telah menambahkan sekitar 60 halaman informasi, dan itu hanya untuk tim kami (~ 10 orang).

Sejauh ini, kami menyimpan informasi tentang proyek-proyek saat ini dan masa lalu di sana, dan telah mulai menambahkan informasi tentang aplikasi seperti bagaimana membangunnya dari awal, URL, dan informasi penting lainnya untuk dev yang baru bagi tim.

Salah satu halaman favorit saya di wiki adalah halaman alat dan perpustakaan. Di sana, kami telah mulai menambahkan informasi tentang alat produktivitas dan pustaka favorit kami yang sering kami gunakan, contohnya adalah grepWin untuk pencarian teks di Windows.

Saya sepenuhnya merekomendasikan untuk memeriksa keseluruhan lengkap wiki yang tersedia dan menemukan yang sesuai dengan penggunaan, fungsi, dan lingkungan penyebaran yang Anda inginkan. Saya memilih ScrewTurn karena mudah digunakan, dan kami punya banyak ruang gratis di WinServer lokal kami, tapi YMMV.

MattGWagner
sumber
0

Kami menggunakan Confluence sebagai wiki dan sharepoint untuk dokumen dalam beberapa kasus. Saya percaya bahwa format wiki online adalah yang disukai ketika Anda perlu membagikan informasi ini secara luas dan yang jauh lebih penting ketika dokumen akan diedit dan diperbarui sangat sering. Jadi saya pikir artikel basis pengetahuan lebih baik dimasukkan ke dalam wiki.

Leonid Shirmanov
sumber
0

Kami saat ini memindahkan info kami dari berbagai dokumen yang tersebar di jaringan ke dua lokasi:

  1. Wiki tersedia di intranet kami
  2. Salinan informasi yang terkait dengan server tertentu di server / direktori root.

Untuk diagram jaringan, Network Notepad .

Juga, saat merekam apa, ingatlah untuk merekam mengapa ada sesuatu yang dikonfigurasi seperti itu. Ini membantu mencegah ide yang sepertinya ide bagus berubah menjadi kesalahan.

David
sumber
0

Kami telah menemukan bahwa MediaWiki adalah pemula yang lambat, tetapi begitu orang-orang di luar IT mengetahui betapa mudahnya untuk menambahkan komentar, perubahan, pengeditan dll, itu menjadi sangat diperlukan. Pengembang menggunakannya untuk dokumentasi internal, fasilitas dept. untuk memposting pemberitahuan, dll. Ini berkembang lebih dari sekadar menjadi alat dokumentasi IT.

bren
sumber