Perangkat lunak untuk mengatur dan memelihara dokumentasi, spesifikasi proyek? [Tutup]

15

Saya mencari perangkat lunak untuk mengatur dan memelihara proyek dokumentasi internal, spesifikasi, persyaratan, dll. Saat ini kami menyimpan semua dokumentasi sebagai banyak file MS Word DOC dalam repositori kontrol sumber, yang memberi kami kontrol versi, dan itu bagus. Tetapi Anda tidak dapat mencari informasi ini, membuat tautan di antara mereka, mengategorikan, berkolaborasi.

Persyaratan, preferensi:

  • Nol instal di sisi klien (berbasis WEB).
  • Kontrol versi dokumen.
  • Anotasi dokumen.
  • Tautan dokumen.
  • Pencarian lengkap (semua dokumentasi).
  • MS Word (* .doc) import \ export.
  • Editor teks WYSIWYG.

Sistem yang saya temukan dan coba sejauh ini:

project-management documentation knowledge-management knowledge-base Alex Burtsev
sumber
Apa jenis dokumen proyek yang Anda miliki (teks, grafik, diagram UML, jadwal waktu, spesifikasi teks, cerita pengguna, dll.)? Berapa banyak orang yang harus memeliharanya? Haruskah itu disinkronkan dengan versi / revisi tertentu dari kode sumber Anda?
Doc Brown
@DocBrown, 95% tekstual, 3-5 orang akan menulisnya. Saya tidak sinkron dengan versi produk perangkat lunak tetapi tidak revisi kode sumber.
Alex Burtsev
XWiki terlihat seperti solusi yang bagus gratis, terintegrasi dengan MS Office dengan baik.
Alex Burtsev
1
Ini hampir menjadi duplikat dari program apa yang Anda gunakan untuk menulis dokumentasi teknis? dan banyak jawabannya mirip, tetapi ada argumen yang lebih baik di sana terhadap penggunaan wiki untuk dokumentasi tersebut.
Mark Booth
Bagaimana dengan perangkat lunak manajemen pengetahuan seperti PHPKB ? Ini tidak gratis tetapi tampaknya melayani tujuan Anda dengan sangat baik.
Anirudh Srivastava

Jawaban:

6

Bagaimana dengan sesuatu seperti Sphinx ?

Anda menulis dokumentasi Anda di reStructuredText (sintaksnya mirip dengan Markdown, yang digunakan Stack Overflow) ke dalam file teks biasa (= kontrol versi yang mudah) dan Sphinx memuntahkan halaman HTML.

Dua pengguna Sphinx yang paling menonjol (yang saya tahu) adalah bahasa Python dan TortoiseHG (lihat tautan untuk dokumentasi yang dihasilkan Sphinx).

EDIT:

Saya baru saja membaca bahwa Anda berbicara tentang dokumentasi internal proyek, bukan dokumentasi pengguna akhir.
Menurut pendapat saya, sesuatu seperti Sphinx adalah cara terbaik untuk dokumentasi internal juga (asalkan Anda bisa membuat analis Anda menulis reStructuredText) karena:

  1. Anda dapat dengan mudah mengontrol versi dokumen (dan file teks yang berbeda membutuhkan banyak ruang, jauh lebih sedikit daripada file biner seperti .doc atau .pdf).
  2. Jika pengembang menginginkan file .doc atau .pdf yang dapat dibaca, ia dapat membuatnya dengan Sphinx dari sumbernya.

Jika Sphinx terlalu rumit, bahkan ada cara yang lebih mudah: Anda dapat menulis dokumentasi Anda di Markdown dan menggunakan Pandoc untuk membuat (misalnya) file .rtf, .doc atau .pdf (ini dapat melakukan lebih banyak lagi).
Saya menemukan Pandoc lebih mudah untuk memulai daripada Sphinx, tetapi Pandoc tidak dapat membuat hierarki menu yang bagus seperti Sphinx (seperti dalam dokumentasi Python dan TortoiseHG yang saya tautkan di atas).

Apa pun alat yang Anda gunakan, jika Anda memiliki server web internal dan server build, Anda dapat mengaturnya sehingga server build menghasilkan output HTML dan menyalinnya di server web setiap kali seseorang mendorong sesuatu ke dokumentasi. Jadi analis Anda bahkan tidak perlu memikirkan hasil akhir, mereka hanya perlu berkomitmen dan mendorong perubahan mereka.

Christian Specht
sumber
Sepertinya itu hanya menghasilkan HTML maka saya harus mempublikasikannya di server web
Alex Burtsev
1
@AlexBurtsev: Jika Anda ingin publik, maka ya. Di sisi lain - sekarang Anda menggunakan file .doc Word, jadi Anda harus meletakkannya di server web juga jika Anda ingin publik.
Christian Specht
Saya perhatikan bahwa Sphinx memiliki jalur "output ke PDF".
Robert Harvey
@ChristianSpecht, Wiki dan Wordpress memiliki plugin untuk mengimpor file Word Doc.
Alex Burtsev
@AlexBurtsev: Saya tidak yakin apakah saya mengerti apa yang ingin Anda lakukan dengan dokumentasi. Jika Anda ingin meletakkannya di web, maka Anda memerlukan beberapa jenis server web, tidak masalah jika Anda menggunakan Sphinx, Wordpress, unduhan .doc atau yang lainnya. Jika Anda perlu mendistribusikan dokumentasi dengan perangkat lunak shrink-wrap, Anda dapat menggunakan Sphinx untuk menghasilkan file bantuan PDF atau Windows.
Christian Specht
5

Nah, Anda bisa mencoba menerapkan Wiki. Mediawiki memiliki semua fitur yang hilang yang Anda bicarakan (fungsi pencarian, riwayat versi, tautan, kategorisasi). Anda harus memastikan bahwa Anda mengetahui versi dokumentasi mana yang dimiliki versi perangkat lunak mana, tetapi itu dapat dilakukan dengan konvensi menyertakan referensi versi atau kategori tertentu di setiap artikel yang bergantung versi.

TAPI: Anda menulis bahwa Anda memiliki "analis" yang bukan pengembang (saya akui, saya bukan penggemar konstelasi itu). Orang-orang semacam itu sering tidak senang ketika Anda mengganti alat MS Office mereka dengan beberapa alat berorientasi teks seperti Wiki. Dan karena MS-Word bukan perangkat lunak bebas, maka saya rasa persyaratan "perangkat lunak bebas" tidak benar-benar suatu keharusan. Dalam situasi ini, server Sharepoint mungkin merupakan alternatif yang lebih baik. Tidak gratis, tetapi AFAIK memiliki semua fitur yang Anda minta, dan dokumen masih dapat dibuat menggunakan Word, Excel dll.

Doc Brown
sumber
1
Kami sudah memiliki server SharePoint tetapi pengembang tidak menyukainya, dan tidak ingin menggunakannya (saya sendiri pengembang). Kami menginginkan sesuatu di mana kami dapat dengan mudah menemukan informasi yang kami butuhkan. Informasi yang dikategorikan dan ditautkan.
Alex Burtsev
@AlexBurtsev: Saya belum pernah menggunakan server Sharepoint sendiri, tetapi saya mendapat kesan bahwa Sharepoint menyediakan semua fitur yang Anda gambarkan. Tetapi jika Anda lebih suka Wiki, Mediawiki akan baik-baik saja untuk Anda. Namun, Anda akan melakukan upaya awal untuk menginstalnya, menetapkan beberapa struktur garis besar, dan juga menetapkan beberapa konvensi bagaimana menggunakan / tidak menggunakannya.
Doc Brown
Saya saat ini sedang mencoba XWiki untuk integrasi MS Office
Alex Burtsev
@DocBrown - SharePoint mengerikan. Tidak intuitif, labirin lengkap tab dan sub-tab, dan tidak mempertahankan kontrol versi yang tepat. Siapa pun yang menggunakannya akan lebih baik membuang semua dokumen mereka ke direktori bersama di server internal. Wiki biasanya merupakan cara untuk melakukan hal semacam ini.
Polinomial
2

Itu selalu lebih baik untuk menjaga spesifikasi dan dokumentasi di bawah kontrol versi karena akan memberi Anda pengaruh terbesar meskipun kurva belajar akan sedikit curam. Dalam hal mesin pengetahuan, saya merekomendasikan yang berikut ini

  1. Trac - Sistem pelacakan bug dan mesin pengetahuan yang mudah digunakan. Ditulis dengan Python dan extensible, Anda akan siap dan berjalan dalam beberapa menit
  2. MoinMoin - Mesin wiki lengkap. Lagi-lagi Python dengan banyak fitur

Keduanya memiliki antarmuka minimal, mendukung sebagian besar struktur wiki, cukup mudah digunakan dan dipelihara, mendukung revisi, memiliki editor WYSIWYG yang baik dan Anda bahkan dapat menyimpan dokumentasi dan spesifikasi Anda juga. Kecuali proyek Anda sangat besar, Anda dapat memilih salah satu di atas.

Ubermensch
sumber
2

Kami baru-baru ini mulai menggunakan Alfresco DMS yang memiliki banyak properti menarik:

  • Instal sangat sederhana
  • Memiliki pengindeks built-in untuk pencarian cepat melalui tumpukan dokumen
  • Mengizinkan alur kerja, grup, dan jika perlu, akses spesifik ke dokumen oleh pelanggan
  • Sumber terbuka
  • Komunitas aktif
  • Integrasi LDAP / AD / SSO
  • Menangani banyak dokumen berbeda

Ada juga beberapa kelemahannya:

  • Antarmuka pengguna tidak selalu intuitif
  • Ini sebenarnya bukan wiki, jadi kerja kolaboratif simultan pada satu dokumen mungkin agak rapuh

Jika Anda memutuskan untuk mencobanya, silakan hubungi saya dengan pendapat Anda.

Dibbeke
sumber
0

Kemungkinan lain mungkin menggunakan LaTeX atau format teks lainnya (mungkin texinfo atau bahkan lout ) untuk dokumentasi. Bagian-bagiannya dapat dihasilkan mesin. Ada beberapa alat untuk konversi HTML, seperti HeVeA untuk mengonversi LaTeX ke HTML. Anda juga dapat menggunakan doxygen untuk menghasilkan dokumentasi dari komentar terstruktur di dalam kode sumber Anda. Dan bagian tulisan tangan dari dokumentasi dapat (dan harus) dikelola sebagai kode sumber (mis. Versi kontrol dan pembuatan).

Basile Starynkevitch
sumber
Saya tidak berbicara tentang dokumentasi produk perangkat lunak (bantuan, manual). Saya berbicara tentang spesifikasi perangkat lunak, persyaratan bisnis.
Alex Burtsev
Anda dapat menulis spesifikasi perangkat lunak atau dokumen teknis apa pun di LaTeX, dan di beberapa lingkaran itu adalah praktik umum.
Basile Starynkevitch
2
LaText, entah bagaimana, mengingatkan saya pada * NIX, dan analis kami tidak pernah memiliki OS semacam itu -), mereka hidup di dunia Windows, dan tidak akan menyetujui sesuatu yang lebih sulit daripada Word untuk input teks.
Alex Burtsev
-2

Saya sarankan menggunakan alat UML dan ERD, di samping dokumen Anda. Anda juga dapat menyimpan dokumen-dokumen ini di ZOHO di ZOHO-Docs , yang tidak gratis, tetapi sangat murah dan memungkinkan fasilitas pencarian dokumen.

Apa pun alat yang akhirnya Anda gunakan, Anda perlu mengatur konten dokumen dengan cermat untuk dapat menggunakan pencarian teks dan mendapatkan hasil yang bermakna. Mendokumentasikan organisasi konten bersama dengan penamaan file yang pintar dan standar dapat sangat membantu.

Tidak mungkin
sumber