Bạn sử dụng công cụ/định dạng nào để viết thông số kỹ thuật của mình?

Question

Tôi muốn biết bạn sử dụng loại công cụ nào để viết thông số kỹ thuật của mình. Tôi nghĩ rằng nó là điều cần thiết để sử dụng một công cụ hỗ trợ một số loại định dạng văn bản đơn giản để người ta có thể kiểm soát các đặc điểm kỹ thuật với một hệ thống kiểm soát nguồn như SVN. Đối với các đặc điểm kỹ thuật như cho mã là tốt, điều quan trọng là phải có một lịch sử của tất cả các thay đổi.

Hiện tại chúng tôi viết đặc tả của chúng tôi ở định dạng XML. TeX cũng sẽ là một lựa chọn thay thế, nhưng thật khó cho những người chưa từng làm việc với nó.

Vì vậy, hãy cho tôi biết, bạn sử dụng loại công cụ hoặc định dạng nào cho thông số kỹ thuật.

Answer 1

DocBook được chỉnh sửa bằng XXE, được dịch sang pdf có xslt khi cần gửi cho khách hàng.

Thay đổi tốt nhất từ ​​trước đến nay, dễ viết hơn nhiều, dễ dàng hơn để hợp nhất và khi được chuyển đổi, nó không quá thiếu chuyên nghiệp như MSWord.

Cộng với kiểu tài liệu có cấu trúc đã có sẵn, không giống như từ đẫm máu mà bạn phải chiến đấu để làm việc.

Answer 2

Tôi đã sử dụng Docbook cho tất cả những thứ như vậy. Thật dễ dàng, linh hoạt, và sẽ tạo ra html, tex (và do đó pdf) vv

Answer 3

Chúng tôi sử dụng TeX (MiKTeX) và nó là hoàn hảo bởi vì:

• sự tố cáo văn bản - chỉnh sửa trong Vim/Notepad -
  chỉ ở khắp mọi nơi
• định dạng mạnh mẽ sử dụng các macro được xác định trước một người trong chúng ta đã làm
• hệ onclick sang PDF

vấn đề duy nhất là để có được sơ đồ (từ ArgoUML) trong.

Tại một dự án khác, tôi thấy sử dụng các mẫu Word - những thứ khủng khiếp được hướng dẫn từ trên cao.

Tôi muốn xem xét sử dụng một cái gì đó như wiki/diễn đàn trên mạng nội bộ. Hãy tưởng tượng sử dụng GoogleDocs - có phiên bản, trực tuyến .. nhưng không áp dụng cho phát triển thương mại.

Answer 4

Microsoft Word. Tôi biết nó không đáp ứng các yêu cầu của bạn nhưng trong mọi công việc tôi đã sử dụng Microsoft Word cho các thông số kỹ thuật. Bạn có thể, và tôi có, đặt các tài liệu Word trong hệ thống kiểm soát nguồn - Điều duy nhất bạn mất là khả năng phân biệt giữa các tài liệu. Mặc dù tôi mơ hồ nhớ đọc ở đâu đó rằng có những công cụ khác nhau cho từ có thể được sử dụng.

Answer 5

Tại nơi làm việc, nhiều tài liệu của chúng tôi nằm trong Sharepoint hoặc một số hệ thống tài liệu khác thực sự làm chậm quá trình "giải phóng" tài liệu. Điều này có nghĩa là có các bản sao của các tài liệu khắp nơi và khiến một người nào đó phát hành đúng thứ gì đó là một cơn đau đầu. Do đó tôi thường nhận được thông số kỹ thuật ở điểm điện hoặc giấy phế liệu. Vì vậy, tôi đã xây dựng một wiki (Media Wiki) tại nơi làm việc mà bây giờ chúng tôi giữ tất cả các thông số dự án. Điều này cho phép họ có thể xem được bất kỳ ai trong công ty và có thể chỉnh sửa bởi nhóm phát triển của chúng tôi. Đôi khi một nhà phát triển sẽ yêu cầu ông chủ làm rõ khi họ đi qua hoặc bất cứ điều gì và các nhà phát triển có thể cập nhật các spec mình mà tôi nghĩ là một lợi thế rất lớn. Ngoài ra, khi mọi người cập nhật thông số với thông tin mới sử dụng lịch sử, rất dễ dàng để xem những thay đổi gần đây nhất là gì - nghĩa là tôi có thể thấy những gì đang diễn ra trước đó và những gì cần phải xảy ra ngay bây giờ.

Tôi vẫn giữ một thông số đã được viết nguệch ngoạc trên một số giấy ghi chú trên tường như một lời nhắc nhở.

Answer 6

Ở nơi làm việc, chúng tôi sử dụng wiki vì chúng rất tuyệt vời để cộng tác, nhưng Microsoft Word sẽ hoạt động.

Bạn thực sự có thể phân biệt hai phiên bản khác nhau của tài liệu Word bằng chính Word - nó sử dụng tính năng "theo dõi thay đổi" để hiển thị sự khác biệt. (Nếu bạn không tin tôi, hãy thử phân biệt hai phiên bản của tài liệu Word bằng TortoiseSVN.)

Đối với tài liệu dài, tôi thực sự thích Word qua wiki vì nó rất phù hợp để chỉnh sửa tài liệu dài và các doanh nghiệp. làm việc thoải mái với tài liệu Word.