Tài liệu ngôn ngữ lập trình: Tài liệu tham khảo

Chúng tôi đang xem xét tài liệu cải tiến trên dòng sản phẩm của chúng tôi. Một phần trong đó bao gồm các hướng dẫn tham khảo cho một ngôn ngữ lập trình được sử dụng như một phần của hệ thống.

Khi viết hướng dẫn tham khảo cho ngôn ngữ lập trình, cách tốt nhất để cấu trúc nó là gì để có thể sử dụng tối đa những người mới sử dụng ngôn ngữ này?

Các khía cạnh quan trọng cho mỗi từ khóa được ghi lại là gì?

• Cú pháp
• Sự miêu tả
• Đối số - nếu có
• Trả về giá trị - nếu có
• Ví dụ về cách sử dụng?
• Có ai khác tôi đang thiếu không?

Các khái niệm (như chiến lược khóa, chi tiết liên quan đến hiệu suất) cũng phải được ghi lại trong tài liệu tham khảo này, hay đó là một tài liệu riêng biệt?

_{Đây là cho tiêu dùng bên ngoài. Chúng tôi đã có bộ tài liệu đầy đủ (xem: http://www.rocketsoftware.com/u2/resource/technical-resource ). Tìm ra những gì chúng ta nên làm khác nhau - tôi đã có ý tưởng của mình, nhưng như mọi khi, tôi cố gắng không chỉ dựa vào ý kiến ​​của mình.}

_{Đối tượng: Các nhà phát triển kỹ thuật sử dụng (các) cơ sở dữ liệu & công cụ của chúng tôi để sản xuất phần mềm trên nhiều ngành.}

Tổ chức tài liệu phù hợp với nhu cầu đối tượng mục tiêu.

Trong trường hợp của bạn, đối tượng chính rõ ràng là nhà phát triển phần mềm. Các phần cần xem xét ở đây là để giải quyết các "đối tượng phụ" khác nhau của nhóm này:

1. Chào thế giới.
   Những người sẵn sàng nhanh chóng có được hương vị của nó, chỉ cần xây dựng và chạy ứng dụng mẫu để xem nó trông như thế nào.
   Hãy nghĩ về khán giả giống như một địa chỉ của MySQL "quy tắc 15 phút" :
   

   _{... một người dùng để có thể kích hoạt MySQL và chạy 15 phút sau khi tải xong.}

2. Nguyên tắc cơ bản.
   Dành cho những người sẵn sàng học hỏi nhanh những thứ cần thiết để bắt đầu sản xuất phần mềm làm việc.
3. Chủ đê nâng cao.
   Đối với các nhà phát triển đã quen thuộc và thực hành với các nguyên tắc cơ bản, quan tâm để biết những gì còn hơn thế. Các chủ đề chính không được đề cập trong Nguyên tắc cơ bản .
4. Hướng dẫn phong cách / Thực hành đề xuất.
   Lời khuyên và hướng dẫn chủ quan cho những người quan tâm đến cách bạn đề xuất làm việc.
   _{Câu hỏi không cho biết liệu điều này có thể có một đối tượng đáng kể trong trường hợp của bạn hay không, vì vậy các tùy chọn để xem xét là đưa nó vào như một phần / phụ lục của các chủ đề Nâng cao hoặc thậm chí loại bỏ hoàn toàn.}
5. Quirks.
   Các chủ đề tối nghĩa, bên ngoài dòng chính, có thể được quan tâm đến một phần khá hạn chế đối tượng của bạn. Ví dụ: nếu bạn có dòng kế thừa hoặc những thứ như nâng cấp / di chuyển / khả năng tương tác với di sản - hãy đặt nó ở đây. Nếu có một số tác dụng phụ cho một số chức năng trong môi trường "kỳ lạ" cụ thể, thì nó sẽ nằm trong phần này.

^{Điều gì nếu một cái gì đó trong hướng dẫn là nghi vấn / mơ hồ? Điều gì sẽ xảy ra nếu giải thích cặn kẽ về các khái niệm cụ thể sẽ làm cho hướng dẫn đó quá khó đọc? Điều gì xảy ra nếu phiên bản cụ thể của hướng dẫn sử dụng có lỗi?}

Hai điều cần xem xét cho người bảo trì là:

1. Thông số kỹ thuật / chính thức.
   Bất cứ khi nào có một chủ đề nghi vấn / mơ hồ / khó giải thích trong hướng dẫn, người đọc có thể được đề cập đến đoạn cụ thể trong đặc tả cho một tuyên bố "chính thức" nghiêm ngặt và rõ ràng về điều đó. Mô tả nghiêm ngặt và đầy đủ (và rất có thể nhàm chán) về cú pháp ngôn ngữ sẽ tốt hơn ở đó.
   Các cân nhắc của Paramount cho Đặc điểm kỹ thuật là độ chính xác và đầy đủ về mặt kỹ thuật, ngay cả khi chúng có chi phí dễ đọc.
2. Bổ sung trực tuyến.
   Chỉ cần đặt trước một số URL và đặt nó vào đầu mỗi tài liệu bạn phát hành, để các chàng trai tự hỏi cái quái gì họ vừa đọc có thể đến đó (thay vì làm phiền những người bảo trì thủ công) và tìm ra lỗi được giải thích.

   _{Errata> Nguyên tắc cơ bản> Phát hành 2.2> Typo ở trang 28, câu thứ hai bắt đầu bằng may mắn , thay vào đó hãy đọc khóa .}

Ví dụ, những người bảo trì thủ công rõ ràng sẽ quan tâm đến một mô tả chính xác, đầy đủ về đồng thời và khóa trong đặc tả chính thức - đặt nó ở đó. Độc giả của các chủ đề cơ bản hoặc nâng cao có thể quan tâm đến tổng quan / giới thiệu / hướng dẫn được trích xuất từ ​​đặc điểm kỹ thuật và phù hợp với nhu cầu của họ, v.v.

_{Có thể hữu ích để sắp xếp một nghiên cứu so sánh các tài liệu tham khảo được cung cấp cho các ngôn ngữ khác như ngôn ngữ của bạn. Mục tiêu nghiên cứu này là tận dụng kinh nghiệm có được bởi những người đã làm nó trước đây và học cách tránh những sai lầm mà họ đã gây ra.}

_{Cuối cùng nhưng không kém phần quan trọng, hãy xem xét việc thiết lập phát triển tài liệu theo cách tương tự như phát triển phần mềm. Ý tôi là những thứ như kiểm soát phiên bản, phát hành thường xuyên, theo dõi vấn đề, đảm bảo chất lượng, v.v. Bạn có thể muốn thực hiện một số thỏa hiệp mặc dù nếu nó chỉ ra rằng (các) nhà văn kỹ thuật của bạn không thực sự thoải mái với những thứ như vậy. Chúng ta không muốn có được nội dung nhảm nhí "đổi lại" cho quá trình phát triển hoàn hảo, phải không?}

Điều đầu tiên mà bạn cần làm là đánh giá đối tượng. Đối tượng của bạn là tin tặc hạt nhân Linux hay họ là những nhà thiết kế phần cứng sử dụng các công cụ phần mềm để thực hiện công việc nhưng không quan tâm đến phần mềm và không có nền tảng CS. Các kỹ sư điện có thể không hoàn toàn rõ ràng về sự khác biệt giữa các đối số const và non-const, con trỏ tới các đối tượng so với các tham chiếu, v.v. có thể không là gì nếu họ là lập trình viên C ++.

Điều thứ hai mà bạn cần đánh giá là độ chi tiết của các nguyên thủy của ngôn ngữ. Độ chi tiết càng mịn, bạn sẽ càng cần cung cấp các ví dụ về việc sử dụng gần với các đặc tả cú pháp của từng nguyên thủy. Đó là, nếu bạn có một nguyên thủy cấp thấp tạo ra một số bối cảnh và bạn cần phải vận hành nó với ba nguyên thủy cấp thấp khác trước khi bạn có thể làm bất cứ điều gì hữu ích, thì tốt hơn hết bạn nên có một ví dụ hoàn chỉnh về một số chức năng hữu ích gần gũi bởi trong hướng dẫn. Xem tài liệu openssl trực tuyến để biết ví dụ tuyệt vời về tài liệu gần như không sử dụng được.

Hãy chắc chắn bao gồm giải thích về bất kỳ tác dụng phụ của chức năng của bạn.

Trong mọi trường hợp, nếu bạn không muốn các lập trình viên của khách hàng nguyền rủa bạn mỗi tối trước khi đi ngủ, hãy bao gồm nhiều mã ví dụ được thử nghiệm thực hiện một số nguyên hàm chức năng cấp cao. Hãy chắc chắn rằng các ví dụ không chỉ là các đoạn mã, mà là đầy đủ và có thể biên dịch hoặc có thể chạy được.

Theo truyền thống, các nhà văn công nghệ đã phân biệt giữa hướng dẫn tham khảo và hướng dẫn sử dụng . Hướng dẫn tham khảo thường bao gồm các đặc tả cú pháp, định nghĩa dễ hiểu về các chức năng hoặc nguyên thủy, thảo luận về gotcha, hiệu suất và tác dụng phụ và cách sử dụng ví dụ ngắn. Hướng dẫn sử dụng bao gồm các ví dụ sử dụng mở rộng hơn và thảo luận về các vấn đề kỹ thuật rộng hơn. "Ngôn ngữ lập trình C" của Kernigan và Ritchie là một ví dụ tuyệt vời cho quy ước này, nhưng cách tiếp cận này chỉ hoạt động khi ngôn ngữ bạn đang ghi chép tương đối đơn giản.

Tác giả là quản lý của Bộ phận Dịch vụ Kỹ thuật tại trung tâm phát triển của Ready Systems Inc. từ năm 1987 đến năm 1991 với trách nhiệm quản lý một nhóm gồm năm nhà văn công nghệ.