Nhóm của bạn sử dụng các công cụ nào để viết hướng dẫn sử dụng?

Question

yêu cầu cơ bản là:

• nhân dạng có thể đọc/văn bản (để dễ dàng kiểm soát phiên bản)
• trực tuyến (đối với hợp tác)
• dễ dàng định dạng (markdown ok, html là quá nhiều)
• định dạng nghiêm ngặt (do đó tác giả không phát minh ra các loại tiêu đề mới, viên đạn, v.v.)
• có thể xuất sang PDF, HTML
• sao lưu và triển khai dễ dàng (để chúng tôi có thể "triển khai" cho c ustomers site là chỉ đọc phiên bản)

Chúng tôi đang nghĩ đến việc sử dụng một loại công cụ wiki, nhưng nó sẽ cần sử dụng tệp để lưu trữ hoặc có phương tiện khác "triển khai" cho khách hàng và dễ cài đặt/maintan. Ngoài ra, nó sẽ phải miễn phí/giá rẻ (hợp lưu là quá đắt)

Bất kỳ đề xuất nào?

Chỉnh sửa: Tôi không tìm kiếm các công cụ để viết mã, chúng tôi đã sử dụng Sandcastle.

Answer 1

Mặc dù nó không thể trả lời tất cả các yêu cầu của bạn, DokuWiki có thể đáng xem.

Giống như với các wiki khác, nó có simple syntax và có điều khiển phiên bản track revisions, tạo table of contents và tính năng full-text search có thể hữu ích cho hệ thống trợ giúp.

Bạn có thể muốn đánh giá feature list để xem liệu nó có đáp ứng nhu cầu của bạn hay không.

Ngoài ra, dường như cũng có một số tốt collection of avaialble plugins. Mặc dù tôi chưa sử dụng DokuWiki hoặc plugin của nó, có vẻ như các plugin cũng có sẵn cho PDF export.

Answer 2

Chúng tôi sử dụng help and manual cho tệp trợ giúp và thủ công. Không có xuất html, nhưng nó cung cấp trợ giúp html, winhelp, pdf và một số định dạng khác.

Answer 3

thử Dikiwiki

Answer 4

Chúng tôi sử dụng Word. Nó được đưa vào kiểm soát phiên bản của chúng tôi, vì vậy chúng tôi có lịch sử (có một thư mục tài liệu liên quan đến mọi dự án). Định dạng có thể được kiểm soát bằng cách sử dụng các mẫu, tất cả chúng ta đã thiết lập, do đó việc thực hiện các thay đổi dễ dàng thực hiện trong các tiêu chuẩn bố trí. Các tập tin có thể được xuất sang PDF. Bạn có thể xuất bản chúng dưới dạng tài liệu chỉ đọc để chia sẻ với người dùng.

Answer 5

Đối với API của chúng tôi, chúng tôi sử dụng Doxygen, điều này thật tuyệt.

Answer 6

Chúng tôi đang sử dụng wiki. Tôi khuyên bạn nên MoinMoin vì

• rất đơn giản để cài đặt (ngay cả trên một máy tính xách tay)
• rất đơn giản để sao lưu (thậm chí bạn có thể cam kết wiki để một hệ thống kiểm soát phiên bản để đồng bộ hóa nó giữa, nói rằng, máy tính xách tay để sử dụng ẩn).
• cú pháp đẹp
• dễ dàng mở rộng
• Dễ dàng tìm kiếm

Chúng tôi không sử dụng một cái gì đó như Word bởi vì:

• Documentation thối quá nhanh
• Tìm kiếm tất cả các tài liệu là một cơn đau
• Liên kết giữa các bit thông tin là một nỗi đau
• Không diff giữa các phiên bản
• định dạng nhị phân mà craps địa ngục ra khỏi bất kỳ VCS
• Không bookmark sâu
• Tài liệu phát triển quá lớn và sau đó họ trở thành vụng về: Tách (và không tìm kiếm nữa) hoặc chờ đợi rất lâu để tải .

Answer 7

LaTeX

Answer 8

Chúng tôi đã thành công rực rỡ với DocToHelp. Nó hoạt động tốt với tài liệu dựa trên Microsoft Word cũng như các hình thức khác và thậm chí nó còn có một số tính năng tích hợp tuyệt vời cho Visual Studio.

Phần tốt nhất là khi bạn đã có cơ sở tài liệu chính được nhập vào DocToHelp, bạn có thể chọn bất kỳ một trong số định dạng xuất là WinHelp, Trợ giúp HTML, Trợ giúp Java hoặc Trợ giúp Net có thể tìm kiếm đẹp mắt và hấp dẫn.

Answer 9

Bạn không đề cập đến ngôn ngữ/khung mà bạn đang sử dụng. Có những công cụ tài liệu thực sự tốt, nhưng một số công cụ cụ thể cho những gì bạn đang phát triển. Chúng tôi là một cửa hàng C#, vì vậy câu trả lời của tôi sẽ chỉ áp dụng cho bạn nếu bạn đang sử dụng .NET.

Chúng tôi sử dụng Sandcastle, không chỉ miễn phí, mà còn là nguồn mở. Trong khi mọi người chủ yếu coi nó như một ứng dụng tạo tài liệu từ Tài liệu XML, bạn có thể cung cấp nội dung của riêng bạn trong MAML. Nó có thể nhắm mục tiêu cả triển khai CHM và trang web, đáp ứng nhu cầu của chúng tôi. Có một số công cụ bổ sung có thể cung cấp những thứ như đánh dấu mục yêu thích và xếp hạng chủ đề theo sự hiểu biết của tôi, nhưng chúng tôi chưa bắt đầu sử dụng chúng.

Điều này cung cấp cho chúng tôi cả tài liệu nội bộ lẫn bên ngoài. Vì chúng tôi cũng sử dụng Team Foundation Server, chúng tôi sử dụng Wiki được xây dựng trong Dự án nhóm trong Sharepoint, nhưng điều đó hướng đến cộng tác dự án.

Chỉnh sửa: Cố định liên kết bị hỏng và cũng muốn đề cập rằng có các công cụ khác kết hợp với Sandcastle mà chúng tôi sử dụng. Những thứ như Sandcastle Help File Builder và GhostDoc là các công cụ phổ biến. Người đầu tiên chỉnh sửa các dự án Sandcastle và MAML và thứ hai để cải thiện chất lượng nhận xét trong mã.

Answer 10

Để tránh mã tôi sử dụng Doxigen. Tôi thích phiên bản Linux, tôi đã gặp sự cố với một vài tính năng trong phiên bản Windows

Answer 11

Đối với "sách hướng dẫn", Docbook. Đó là một phương ngữ SGML được thiết kế cho tài liệu kỹ thuật. http://www.docbook.org/. Nó có thể không đáp ứng tiêu chí "dễ dàng đánh dấu" của bạn nhưng nó chắc chắn tạo ra đầu ra tốt đẹp trong LaTex (có thể được chuyển đổi thành PDF) và đầu ra HTML tốt nếu bạn tự tạo CSS stylesheet cho nó. Các tệp văn bản được giữ trong điều khiển phiên bản.Tất cả các chương trình cũng sử dụng một thư viện kết hợp phân tích cú pháp dòng lệnh với đầu ra "--help" trong một lựa chọn định dạng (bình thường, trang man và docbook). Đối với tham chiếu API, doxygen tất nhiên.

Answer 12

Tại công việc hiện tại của mình, chúng tôi tung ra phần mềm sử dụng một lần để tài liệu thường được đặt ở bên lề và được thực hiện trong Word.

Tại công việc cuối cùng của tôi, nhóm tài liệu dường như liên tục rant và rave khoảng mad cap software's product "Flare". Nó cho phép bạn viết ở một định dạng và xuất bản sang nhiều phương tiện để hướng dẫn sử dụng cũng có thể là trợ giúp trực tuyến hoặc trang web của bạn, v.v ...

Answer 13

Công ty của tôi sử dụng hầu hết các tài liệu. Chúng tôi cũng có một chàng trai biên soạn các công cụ thành các định dạng MS Word và PDF để in/gửi cho khách hàng. Tôi khuyên bạn nên tránh TikiWiki như bệnh dịch hạch. MediaWiki rất tuyệt, vì nó rất dễ sử dụng và bởi vì mọi người đều biết cách sử dụng nó - đó là wiki chuẩn trên thực tế, và xứng đáng như vậy, IMHO.

Answer 14

Trong một thời gian chúng tôi đang sử dụng DocBook, nhưng rất khó mở rộng với các tính năng nâng cao và cần thiết hơn (đánh dấu cú pháp, chia thành nhiều tệp, quản lý đa ngôn ngữ, v.v.). Sau đó, chúng tôi quyết định viết hệ thống của riêng mình từ đầu và phát hành nó như là mã nguồn mở: link text. Nó sử dụng các tệp văn bản thuần túy và Markdown làm ngôn ngữ cú pháp, và bây giờ chúng ta có mọi thứ chúng ta cần. Điểm bất lợi là hiện tại có lẽ không có trình phân tích cú pháp Markdown nào tạo ra một thứ gì đó khác với đầu ra HTML. Bây giờ điều này là đủ, nhưng chúng tôi đang suy nghĩ về việc triển khai hỗ trợ PDF khá sớm.

Hơn nữa, chúng tôi đang duy trì MediaWiki như một trợ giúp dựa vào cộng đồng.

Answer 15

Tôi không thể nói đủ điều tốt về Asciidoc. Nó có cú pháp đánh dấu rất đơn giản, có thể tạo mọi thứ từ pdf tới roff, di động để triển khai và rất dễ dàng chèn vào bất kỳ wiki nào chỉ với một vài thay đổi nhỏ.

Ngay cả trong trạng thái đánh dấu, nó rất, rất dễ đọc. Điều duy nhất tôi phải fiddle với khi sử dụng nó là bảng, nhưng đó không phải là quá khó khăn.

Nếu bạn giữ các tập tin định dạng văn bản trong kho lưu trữ của bạn, theo dõi sửa đổi là khá đơn giản.

Đối với mã doumentation, tôi sử dụng Doxygen.

Answer 16

Pandoc là một công cụ tuyệt vời để chuyển đổi giữa các định dạng đánh dấu khác nhau. Chúng tôi viết tài liệu trong markdown và sử dụng Pandoc để chuyển đổi sang các định dạng khác.

Từ trang web pandoc:

Nếu bạn cần phải chuyển đổi tập tin từ một định dạng đánh dấu vào một, pandoc là dao swiss-quân đội của bạn. Pandoc thể đọc markdown và (tập con của) reStructuredText, dệt, HTML, và LaTeX, và nó có thể viết đồng bằng văn bản, markdown, reStructuredText, HTML, LaTeX, bối cảnh, PDF, RTF, DocBook XML, OpenDocument XML , ODT, GNU Texinfo, Đánh dấu, dệt, groff người đàn ông trang, chế độ org Emacs, EPUB ebooks, và trình chiếu HTML S5 và Slidy. PDF đầu ra (qua LaTeX) cũng được hỗ trợ với trình bao bọc markdown2pdf bao gồm tập lệnh.

Pandoc được thêm điểm cho là mã nguồn mở và được viết trong sự nóng bỏng đó là Haskell;)

Answer 17

Hãy thử Sphinx. Tất cả tài liệu python được thực hiện bằng công cụ này http://docs.python.org/