tài liệu

Tài liệu phần mềm được viết bằng văn bản hoặc hình minh họa đi kèm với phần mềm máy tính hoặc được nhúng trong mã nguồn. Nó hoặc giải thích cách nó hoạt động hoặc cách sử dụng nó, và có thể có nghĩa là những thứ khác nhau cho mọi người trong các vai trò khác nhau.

Tài liệu là một phần quan trọng của công nghệ phần mềm. Các loại tài liệu bao gồm:

  1. Yêu cầu – Báo cáo xác định các thuộc tính, khả năng, đặc điểm hoặc phẩm chất của một hệ thống. Đây là nền tảng cho những gì sẽ hoặc đã được thực hiện.
  2. Architecture / Design – Tổng quan về phần mềm. Bao gồm các mối quan hệ với các nguyên tắc môi trường và xây dựng được sử dụng trong thiết kế các thành phần phần mềm.
  3. Kỹ thuật – Tài liệu về mã, thuật toán, giao diện và API.
  4. Người dùng cuối – Hướng dẫn cho người dùng cuối, quản trị viên hệ thống và hỗ trợ staff.
  5. Marketing – Cách tiếp thị sản phẩm và phân tích nhu cầu thị trường.

Tài liệu yêu cầu [ chỉnh sửa ]

Tài liệu yêu cầu là mô tả về phần mềm cụ thể nào hoặc sẽ làm. Nó được sử dụng trong suốt quá trình phát triển để truyền đạt cách thức hoạt động của phần mềm hoặc cách thức hoạt động của nó. Nó cũng được sử dụng như một thỏa thuận hoặc là nền tảng cho thỏa thuận về những gì phần mềm sẽ làm. Các yêu cầu được sản xuất và tiêu thụ bởi mọi người tham gia sản xuất phần mềm: người dùng cuối, khách hàng, quản lý sản phẩm, quản lý dự án, bán hàng, tiếp thị, kiến ​​trúc sư phần mềm, kỹ sư khả năng sử dụng, nhà thiết kế tương tác, nhà phát triển và người thử nghiệm. Vì vậy, tài liệu yêu cầu có nhiều mục đích khác nhau.

Yêu cầu có nhiều kiểu dáng, ký hiệu và hình thức. Các yêu cầu có thể giống như mục tiêu (ví dụ: môi trường làm việc phân tán ), gần với thiết kế (ví dụ: các bản dựng có thể được bắt đầu bằng cách nhấp chuột phải vào tệp cấu hình và chọn chức năng 'xây dựng' ), và bất cứ điều gì ở giữa. Chúng có thể được chỉ định là các câu lệnh trong ngôn ngữ tự nhiên, như các hình vẽ, như các công thức toán học chi tiết và là sự kết hợp của tất cả chúng.

Sự biến đổi và phức tạp của tài liệu yêu cầu làm cho nó trở thành một thách thức đã được chứng minh. Yêu cầu có thể là ngầm và khó để khám phá. Thật khó để biết chính xác bao nhiêu và loại tài liệu nào là cần thiết và bao nhiêu có thể để lại cho tài liệu kiến ​​trúc và thiết kế, và rất khó để biết làm thế nào để ghi lại các yêu cầu xem xét sự đa dạng của những người sẽ đọc và sử dụng tài liệu . Vì vậy, tài liệu yêu cầu thường không đầy đủ (hoặc không tồn tại). Không có tài liệu yêu cầu phù hợp, các thay đổi phần mềm trở nên khó khăn hơn – và do đó dễ bị lỗi hơn (giảm chất lượng phần mềm) và tốn thời gian (tốn kém).

Nhu cầu về tài liệu yêu cầu thường liên quan đến độ phức tạp của sản phẩm, tác động của sản phẩm và tuổi thọ của phần mềm. Nếu phần mềm rất phức tạp hoặc được phát triển bởi nhiều người (ví dụ: phần mềm điện thoại di động), các yêu cầu có thể giúp truyền đạt tốt hơn những gì cần đạt được. Nếu phần mềm rất quan trọng về an toàn và có thể có tác động tiêu cực đến cuộc sống của con người (ví dụ: hệ thống điện hạt nhân, thiết bị y tế, thiết bị cơ khí), thường cần có tài liệu yêu cầu chính thức hơn. Nếu phần mềm dự kiến ​​chỉ tồn tại trong một hoặc hai tháng (ví dụ: các ứng dụng điện thoại di động rất nhỏ được phát triển riêng cho một chiến dịch nhất định) có thể cần rất ít tài liệu yêu cầu. Nếu phần mềm là bản phát hành đầu tiên được xây dựng sau này, tài liệu yêu cầu rất hữu ích khi quản lý thay đổi phần mềm và xác minh rằng không có gì bị hỏng trong phần mềm khi phần mềm được sửa đổi.

Theo truyền thống, các yêu cầu được chỉ định trong các tài liệu yêu cầu (ví dụ: sử dụng các ứng dụng xử lý văn bản và ứng dụng bảng tính). Để quản lý sự phức tạp gia tăng và thay đổi bản chất của tài liệu yêu cầu (và tài liệu phần mềm nói chung), các hệ thống tập trung vào cơ sở dữ liệu và các công cụ quản lý yêu cầu cho mục đích đặc biệt được ủng hộ.

Tài liệu thiết kế kiến ​​trúc [ chỉnh sửa ]

Tài liệu kiến ​​trúc (còn được gọi là mô tả kiến ​​trúc phần mềm) là một loại tài liệu thiết kế đặc biệt. Theo một cách nào đó, tài liệu kiến ​​trúc là đạo hàm thứ ba từ mã (tài liệu thiết kế là đạo hàm thứ hai và tài liệu mã là đầu tiên). Rất ít trong các tài liệu kiến ​​trúc là cụ thể cho chính mã. Các tài liệu này không mô tả cách lập trình một thói quen cụ thể, hoặc thậm chí tại sao thói quen cụ thể đó tồn tại ở dạng mà nó làm, mà thay vào đó chỉ đưa ra các yêu cầu chung sẽ thúc đẩy sự tồn tại của thói quen đó. Một tài liệu kiến ​​trúc tốt là ngắn về chi tiết nhưng dày về giải thích. Nó có thể gợi ý các cách tiếp cận cho thiết kế cấp thấp hơn, nhưng để lại các nghiên cứu thương mại thăm dò thực tế cho các tài liệu khác.

Một loại tài liệu thiết kế khác là tài liệu so sánh, hoặc nghiên cứu thương mại. Điều này thường có dạng whitepaper . Nó tập trung vào một khía cạnh cụ thể của hệ thống và đề xuất các phương pháp thay thế. Nó có thể là ở giao diện người dùng, mã, thiết kế hoặc thậm chí ở cấp độ kiến ​​trúc. Nó sẽ phác thảo tình huống là gì, mô tả một hoặc nhiều lựa chọn thay thế và liệt kê những ưu và nhược điểm của từng loại. Một tài liệu nghiên cứu thương mại tốt là nặng về nghiên cứu, thể hiện ý tưởng của nó rõ ràng (mà không phụ thuộc nhiều vào thuật ngữ khó hiểu để làm lóa mắt người đọc), và quan trọng nhất là vô tư. Nó nên giải thích trung thực và rõ ràng chi phí của bất kỳ giải pháp nào nó cung cấp là tốt nhất. Mục tiêu của một nghiên cứu thương mại là đưa ra giải pháp tốt nhất, thay vì thúc đẩy một quan điểm cụ thể. Hoàn toàn có thể chấp nhận được khi không đưa ra kết luận nào, hoặc kết luận rằng không có lựa chọn thay thế nào đủ tốt hơn đường cơ sở để đảm bảo thay đổi. Nó nên được tiếp cận như một nỗ lực khoa học, không phải là một kỹ thuật tiếp thị.

Một phần rất quan trọng của tài liệu thiết kế trong phát triển phần mềm doanh nghiệp là Tài liệu thiết kế cơ sở dữ liệu (DDD). Nó chứa các yếu tố thiết kế khái niệm, logic và vật lý. DDD bao gồm thông tin chính thức mà những người tương tác với cơ sở dữ liệu cần. Mục đích của việc chuẩn bị nó là tạo ra một nguồn chung được sử dụng bởi tất cả người chơi trong cảnh. Những người dùng tiềm năng là:

Khi nói về Hệ thống cơ sở dữ liệu quan hệ, tài liệu nên bao gồm các phần sau:

  • Thực thể – Lược đồ mối quan hệ (được tăng cường hay không), bao gồm các thông tin sau và định nghĩa rõ ràng của chúng:
    • Các tập hợp thực thể và các thuộc tính của chúng
    • Mối quan hệ và thuộc tính của chúng
    • Các khóa ứng cử viên cho mỗi tập thực thể
    • Các ràng buộc dựa trên thuộc tính và Tuple
    • Các bảng, thuộc tính và các thuộc tính của chúng
    • Lượt xem
    • Các ràng buộc như khóa chính, khóa ngoại,
    • Chính sách của các ràng buộc tham chiếu
    • Chính sách xếp chồng cho các ràng buộc tham chiếu
    • là rất quan trọng để bao gồm tất cả các thông tin sẽ được sử dụng bởi tất cả các diễn viên trong cảnh. Nó cũng rất quan trọng để cập nhật các tài liệu vì bất kỳ thay đổi xảy ra trong cơ sở dữ liệu là tốt.
    • Tài liệu kỹ thuật [ chỉnh sửa ]
    • Điều quan trọng đối với các tài liệu mã được liên kết với mã nguồn (có thể bao gồm các tệp README và tài liệu API) là triệt để, nhưng không quá dài dòng rằng nó trở nên quá tốn thời gian hoặc khó khăn để duy trì chúng. Các hướng dẫn tài liệu hướng dẫn và tổng quan khác nhau thường được tìm thấy cụ thể cho ứng dụng phần mềm hoặc sản phẩm phần mềm đang được các nhà văn API ghi lại. Tài liệu này có thể được sử dụng bởi các nhà phát triển, người thử nghiệm và cả người dùng cuối sử dụng ứng dụng phần mềm. Ngày nay, rất nhiều ứng dụng cao cấp trong lĩnh vực năng lượng, năng lượng, giao thông vận tải, mạng, hàng không vũ trụ, an toàn, an ninh, tự động hóa công nghiệp và một loạt các lĩnh vực khác được nhìn thấy. Tài liệu kỹ thuật đã trở nên quan trọng trong các tổ chức như mức thông tin cơ bản và nâng cao có thể thay đổi trong một khoảng thời gian với sự thay đổi kiến ​​trúc.
    • Tài liệu mã thường được sắp xếp theo kiểu hướng dẫn tham khảocho phép lập trình viên nhanh chóng tra cứu một chức năng hoặc lớp tùy ý.
    • Tài liệu kỹ thuật được nhúng trong mã nguồn [chỉnh sửa ]
    • Thông thường, các công cụ như Doxygen, NDoc, Visual Expert, Javadoc, EiffelStudio, Sand Castle, ROBODoc, POD, TwinText, hoặc Universal Báo cáo có thể được sử dụng để tự động tạo tài liệu mã, đó là, họ trích xuất các nhận xét và hợp đồng phần mềm, nếu có, từ mã nguồn và tạo hướng dẫn tham khảo ở dạng như văn bản hoặc tệp HTML.
    • Ý tưởng về tài liệu tạo tự động rất hấp dẫn đối với các lập trình viên vì nhiều lý do. Ví dụ, vì được trích xuất từ ​​chính mã nguồn (ví dụ, thông qua các bình luận), lập trình viên có thể viết nó trong khi tham khảo mã và sử dụng cùng các công cụ được sử dụng để tạo mã nguồn để tạo tài liệu. Điều này làm cho việc cập nhật tài liệu dễ dàng hơn nhiều.
    • Tất nhiên, một nhược điểm là chỉ lập trình viên mới có thể chỉnh sửa loại tài liệu này và nó phụ thuộc vào họ để làm mới đầu ra (ví dụ: bằng cách chạy một công việc định kỳ để cập nhật tài liệu hàng đêm). Một số người sẽ mô tả điều này như một pro chứ không phải là một con.
    • Lập trình biết chữ [ chỉnh sửa ]
    • Nhà khoa học máy tính đáng kính Donald Knuth đã lưu ý rằng tài liệu có thể là một quá trình suy nghĩ rất khó khăn và đã ủng hộ lập trình biết chữ, được viết cùng lúc và địa điểm như mã nguồn và trích xuất bằng phương tiện tự động. Các ngôn ngữ lập trình Haskell và CoffeeScript có hỗ trợ tích hợp cho một hình thức lập trình biết chữ đơn giản, nhưng hỗ trợ này không được sử dụng rộng rãi.
    • Lập trình Elucidative [ chỉnh sửa ]
    • Lập trình Elucidative là kết quả của các ứng dụng thực tế của Lập trình Văn học trong bối cảnh lập trình thực. Mô hình Elucidative đề xuất rằng mã nguồn và tài liệu được lưu trữ riêng.
    • Thông thường, các nhà phát triển phần mềm cần có khả năng tạo và truy cập thông tin không phải là một phần của tệp nguồn. Các chú thích như vậy thường là một phần của một số hoạt động phát triển phần mềm, chẳng hạn như đi bộ và chuyển mã, trong đó mã nguồn của bên thứ ba được phân tích theo cách có chức năng. Do đó, các chú thích có thể giúp nhà phát triển trong bất kỳ giai đoạn phát triển phần mềm nào trong đó một hệ thống tài liệu chính thức sẽ cản trở tiến trình.
    • Tài liệu người dùng [ chỉnh sửa ]
    • Không giống như tài liệu mã, tài liệu người dùng chỉ mô tả cách sử dụng chương trình.
    • Trong trường hợp thư viện phần mềm, tài liệu mã và tài liệu người dùng trong một số trường hợp có thể tương đương và có giá trị liên kết một cách hiệu quả, nhưng đối với một ứng dụng chung thì điều này thường không đúng.
    • Thông thường, tài liệu người dùng mô tả từng tính năng của chương trình và hỗ trợ người dùng nhận ra các tính năng này. Một tài liệu người dùng tốt cũng có thể cung cấp hỗ trợ khắc phục sự cố kỹ lưỡng. Điều rất quan trọng là các tài liệu người dùng không bị nhầm lẫn và để chúng được cập nhật. Tài liệu người dùng không cần phải được tổ chức theo bất kỳ cách cụ thể nào, nhưng điều rất quan trọng đối với họ là phải có một chỉ số kỹ lưỡng. Tính nhất quán và đơn giản cũng rất có giá trị. Tài liệu người dùng được coi là hợp đồng xác định phần mềm sẽ làm gì. Nhà văn API rất thành công trong việc viết tài liệu người dùng tốt vì họ sẽ nhận thức rõ về kiến ​​trúc phần mềm và kỹ thuật lập trình được sử dụng. Xem thêm kỹ thuật viết.
    • Tài liệu người dùng có thể được sản xuất ở nhiều định dạng trực tuyến và in. [1] Tuy nhiên, có ba cách rộng rãi để có thể tổ chức tài liệu người dùng.
      1. Hướng dẫn: Cách tiếp cận hướng dẫn được coi là hữu ích nhất cho người dùng mới, trong đó họ được hướng dẫn qua từng bước để hoàn thành các nhiệm vụ cụ thể. [2]
      2. Chuyên đề: Một cách tiếp cận theo chủ đề, trong đó các chương hoặc phần tập trung vào một lĩnh vực cụ thể, được sử dụng chung hơn cho người dùng trung gian. Một số tác giả thích truyền đạt ý tưởng của họ thông qua một bài viết dựa trên kiến ​​thức để tạo thuận lợi cho nhu cầu của người dùng. Cách tiếp cận này thường được thực hiện bởi một ngành công nghiệp năng động, chẳng hạn như Công nghệ thông tin, trong đó dân số người dùng chủ yếu tương quan với các yêu cầu khắc phục sự cố [3]
      3. Danh sách hoặc Tài liệu tham khảo: loại nguyên tắc tổ chức là một trong đó các lệnh hoặc tác vụ được liệt kê đơn giản theo thứ tự bảng chữ cái hoặc nhóm, thường thông qua các chỉ mục được tham chiếu chéo. Cách tiếp cận thứ hai này được sử dụng nhiều hơn cho người dùng nâng cao, những người biết chính xác loại thông tin họ đang tìm kiếm.
    • Một khiếu nại phổ biến của người dùng về tài liệu phần mềm là chỉ một trong ba cách tiếp cận này được đưa ra để loại trừ gần như Hai loại khác. Thông thường giới hạn tài liệu phần mềm được cung cấp cho máy tính cá nhân để trợ giúp trực tuyến chỉ cung cấp thông tin tham khảo về các lệnh hoặc các mục menu. Công việc dạy kèm người dùng mới hoặc giúp người dùng có nhiều kinh nghiệm hơn tận dụng tối đa chương trình được dành cho các nhà xuất bản tư nhân, những người thường được nhà phát triển phần mềm hỗ trợ đáng kể.
    • Soạn tài liệu người dùng [ chỉnh sửa ]
    • Giống như các hình thức tài liệu kỹ thuật khác, tài liệu người dùng tốt được hưởng lợi từ quá trình phát triển có tổ chức. Trong trường hợp tài liệu người dùng, quá trình như thường xảy ra trong công nghiệp bao gồm năm bước: [4]
    • 1. Phân tích người dùng, giai đoạn nghiên cứu cơ bản của quy trình. [5]
    • 2. Lập kế hoạch hoặc giai đoạn tài liệu thực tế. [6]
    • 3. Đánh giá dự thảo giai đoạn tự giải thích trong đó phản hồi được tìm kiếm về dự thảo được sáng tác ở bước trước. [7]
    • 4. Kiểm tra khả năng sử dụng, theo đó khả năng sử dụng của tài liệu được kiểm tra theo kinh nghiệm. [8]
    • 5. Chỉnh sửa, bước cuối cùng trong đó thông tin được thu thập ở bước ba và bốn được sử dụng để tạo bản thảo cuối cùng.
    • Tranh cãi về tài liệu và phát triển nhanh [chỉnh sửa ]
    • "Khả năng chống lại tài liệu giữa các nhà phát triển được biết đến và không cần nhấn mạnh." [9]
    • Tình huống này đặc biệt phổ biến trong phần mềm nhanh. phát triển vì các phương pháp này cố gắng tránh mọi hoạt động không cần thiết không trực tiếp mang lại giá trị.
    • Cụ thể, Tuyên ngôn Agile chủ trương định giá "phần mềm làm việc trên tài liệu toàn diện", có thể được hiểu một cách yếm thế là "Chúng tôi muốn dành toàn bộ thời gian để viết mã. Hãy nhớ rằng, các lập trình viên thực sự không viết tài liệu." [10] ]
    • Tuy nhiên, một cuộc khảo sát giữa các chuyên gia kỹ thuật phần mềm đã tiết lộ rằng tài liệu này không có nghĩa là không cần thiết trong phát triển nhanh.
    • Tuy nhiên, có thể thừa nhận rằng có những vấn đề về động lực trong quá trình phát triển và các phương pháp tài liệu phù hợp với phát triển nhanh (ví dụ như thông qua hệ thống danh tiếng và Gamification) có thể cần thiết. [11][12]
    • Tài liệu tiếp thị [ chỉnh sửa ] [19659010] Đối với nhiều ứng dụng, cần có một số tài liệu quảng cáo để khuyến khích các nhà quan sát thông thường dành nhiều thời gian hơn để tìm hiểu về sản phẩm. Hình thức tài liệu này có ba mục đích: –
      1. Để kích thích người dùng tiềm năng về sản phẩm và truyền cho họ mong muốn được tham gia nhiều hơn với nó.
      2. Để thông báo cho họ về chính xác sản phẩm làm gì, để mong đợi của họ phù hợp với những gì họ sẽ nhận được .
      3. Để giải thích vị trí của sản phẩm này đối với các lựa chọn thay thế khác.
    • Xem thêm [ chỉnh sửa ]
      1. ^ RH Earle, MA Rosso, KE Alexander ( 2015) Sở thích của người dùng về thể loại tài liệu phần mềm. Thủ tục tố tụng của Hội nghị quốc tế thường niên lần thứ 33 về thiết kế truyền thông (ACM SIGDOC).
      2. ^ Woelz, Carlos. "Tài liệu mồi KDE" . Truy cập 15 tháng 6 2009 .
      3. ^ Microsoft. "Các bài viết cơ sở kiến ​​thức để phát triển trình điều khiển" . Truy cập15 tháng 6 2009 .
      4. ^ Thomas T. Barker, Viết tài liệu phần mềm, Lời nói đầu, xxiv. Một phần của Sê-ri Allyn & Bacon trong Truyền thông kỹ thuật, tái bản lần 2. Thượng Yên River: Pearson Education, 2003. ISBN 0321103289 Lưu trữ ngày 13 tháng 5 năm 2013, tại Wayback Machine.
      5. ^ Barker, pg. 118.
      6. ^ Barker, pg. 173.
      7. ^ Barker, pg. 217.
      8. ^ Barker, pg. 240.
      9. ^ Herbsleb, James D. và Moitra, Dependra. Trong: Phần mềm IEEE tập. 18, không 2, trang 16-20, Tháng 3 / Tháng 4 năm 2001
      10. ^ Rakitin, Steven. , "Tuyên ngôn khơi gợi sự hoài nghi." Máy tính IEEE, tập. 34, không 12, tr. 4, 2001
      11. ^ Lời khen ngợi, Christian R. và Zoya Durdik. "Thiết kế kiến ​​trúc và tài liệu: Lãng phí trong phát triển nhanh?" Trong: Hội nghị quốc tế về quy trình phần mềm và hệ thống (ICSSP), IEEE, 2012.
      12. ^ Selic, Bran. "Tài liệu nhanh nhẹn, có ai không?" Trong: Phần mềm IEEE tập. 26, không 6, trang 11-12, 2009
    • Liên kết ngoài [ chỉnh sửa ]