Trong lĩnh vực phát triển của ứng dụng di động, web và nhiều thứ khác nữa, tài liệu (document) đóng một vai trò quan trọng trong việc xác định thành công của ứng dụng. Nhưng nếu bạn đã từng làm tài liệu, bạn sẽ đồng ý với tôi rằng đó là điều ít được các nhà phát triển yêu thích nhất.

Không giống như viết code, tài liệu phải viết làm sao để mọi người dễ dàng tìm hiểu. Về mặt kỹ thuật, chúng ta phải dịch một ngôn ngữ máy (mã) sang một ngôn ngữ có thể hiểu được đối với con người, ngôn ngữ này khó hơn cả code 😀

Mặc dù nó có thể là một gánh nặng thực sự, nhưng việc viết tài liệu rất quan trọng và sẽ mang lại lợi ích cho người dùng, đồng nghiệp của bạn và đặc biệt là chính bạn.

Tài liệu tốt giúp nhiều cho user

Tài liệu giúp người đọc hiểu rõ ràng cách thức hoạt động của code. Nhưng nhiều nhà phát triển đã sai lầm khi cho rằng người sử dụng phần mềm sẽ thành thạo.

Do đó, tài liệu có thể là tài liệu mỏng, bỏ qua rất nhiều yếu tố cần thiết mà nó nên có ngay từ đầu. Nếu bạn hiểu biết về ngôn ngữ, bạn có thể tự tìm hiểu mọi thứ. Nếu bạn không có, thì bạn bị lạc giữa rừng code.

Tài liệu dành cho người dùng thường bao gồm mục đích sử dụng thực tế hoặc cách sử dụng. Quy tắc chung khi tạo tài liệu cho người dùng phổ thông là tài liệu đó phải rõ ràng. Sử dụng các từ thân thiện với con người được ưu tiên hơn các thuật ngữ kỹ thuật hoặc biệt ngữ. Các ví dụ sử dụng thực tế cũng sẽ được đánh giá cao.

Một thiết kế bố cục tốt cũng sẽ thực sự giúp người dùng quét qua từng phần của tài liệu mà không bị mỏi mắt. Một vài ví dụ tốt là tài liệu cho Bootstrap và tài liệu hướng dẫn bắt đầu với WordPress.

Nó giúp các developer khác

Mỗi nhà phát triển sẽ có phong cách viết code riêng của mình. Tuy nhiên, khi nói đến làm việc trong một nhóm, chúng ta thường sẽ phải chia sẻ code với các đồng đội khác. Vì vậy, điều cần thiết là phải có sự đồng thuận về một tiêu chuẩn để giữ mọi người trên “cùng một hệ quy chiếu”. Một tài liệu được viết đúng cách sẽ là tài liệu tham khảo mà nhóm cần.

Nhưng không giống như tài liệu dành cho người dùng cuối, tài liệu này thường mô tả các quy trình kỹ thuật như quy ước đặt tên code, các biến, chỉ ra cách các trang cụ thể nên được tạo và cách API hoạt động cùng với các ví dụ về code.

Ngoài ra, trong trường hợp bạn có thành viên mới tham gia nhóm của mình sau này, các document này có thể là một cách hiệu quả để họ làm quen thay vì tốt rất nhiều thời gian để đào tạo họ.

Nó cũng giúp chính người lập trình

Điều buồn cười về việc viết mã là đôi khi ngay cả chính các nhà phát triển cũng không hiểu được mã mà họ đã viết.

Bạn mới code thì không sao, tuy nhiên trong trường hợp các mã đã được giữ nguyên trong nhiều tháng hoặc thậm chí nhiều năm thì bạn sẽ không nhớ đâu.

Một nhu cầu đột ngột để xem lại các mã vì lý do này hay lý do khác sẽ khiến người ta tự hỏi điều gì đang xảy ra trong tâm trí của họ khi họ viết những mã này.

Đừng ngạc nhiên, điều này rất bình thường!

Bằng cách ghi lại tài liệu cho code của mình, bạn sẽ có thể truy cập đến phần cuối mã của mình một cách nhanh chóng và không bị thất vọng, giúp bạn tiết kiệm rất nhiều thời gian có thể dành cho việc hoàn thành các thay đổi.

Làm thế nào để tạo một document tốt?

Có một số yếu tố giúp xây dựng một phần tài liệu tốt. Một số điều quan trọng nhất như sau:

Đừng tự phán

Đừng cho rằng người dùng của bạn biết những gì bạn biết cũng như những gì họ muốn biết. Tốt hơn hết là nên bắt đầu ngay từ đầu bất kể mức độ thành thạo của người dùng.

Ví dụ: nếu bạn đã xây dựng một plugin jQuery, bạn có thể lấy cảm hứng từ tài liệu của SlickJS. Nó chỉ ra cách cấu trúc HTML, nơi đặt CSS và JavaScript, cách khởi tạo plugin jQuery ở mức cơ bản nhất của nó.

Điểm mấu chốt là tài liệu được viết với quá trình suy nghĩ của người dùng, không phải của nhà phát triển. Tiếp cận tài liệu của riêng bạn theo cách này sẽ cung cấp cho bạn góc nhìn tốt hơn trong việc tổ chức tác phẩm của riêng bạn.

Tuân theo tiêu chuẩn

Khi thêm tài liệu phù hợp với mã, hãy sử dụng tiêu chuẩn mong đợi của ngôn ngữ . Luôn luôn là một ý kiến ​​hay khi mô tả từng hàm, các biến, cũng như giá trị được trả về bởi hàm. Đây là một ví dụ về tài liệu tốt cho ngôn ngữ PHP.

/**
 * Adds custom classes to the array of body classes.
 *
 * @param array $classes Classes for the body element.
 * @return array
 */
function body_classes( $classes ) {
  // Adds a class of group-blog to blogs with more than 1 published author.
  if ( is_multi_author() ) {
    $classes[] = 'group-blog';
  }
 
  return $classes;
}
add_filter( 'body_class', 'body_classes' );

Sau đây là một số tài liệu tham khảo để định dạng tài liệu nội bộ trong PHP, JavaScript và CSS:

• PHP: PHP Documentation Standard for WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

Nếu bạn đang sử dụng SublimeText, tôi khuyên bạn nên cài đặt DocBlockr. Nó sẽ thông minh điền trước code của bạn với hướng dẫn nội bộ.

Yếu tố đồ họa

Sử dụng các yếu tố đồ họa, chúng nói tốt hơn văn bản. Những phương tiện này rất hữu ích, đặc biệt nếu bạn xây dựng phần mềm có giao diện đồ họa. Bạn có thể thêm các yếu tố trỏ như mũi tên, vòng tròn hoặc bất kỳ thứ gì có thể giúp người dùng tìm ra nơi cần đến để hoàn thành các bước mà không cần phỏng đoán.

Sau đây là một ví dụ từ ứng dụng Tower nơi bạn có thể lấy cảm hứng từ đó. Họ giải thích bằng video cách hoạt động, dễ hiểu hơn so với việc sử dụng các dòng lệnh văn bản thuần túy.

Phân đoạn

Bạn có thể cân nhắc gói một vài điều trong tài liệu trong danh sách và bảng có dấu đầu dòng vì điều này làm cho nội dung dài hơn dễ dàng hơn để đọc.

Thêm một bảng nội dung và chia tài liệu thành các phần dễ hiểu, nhưng vẫn giữ cho mỗi phần phù hợp với nội dung tiếp theo. Giữ nó ngắn gọn và đơn giản.

Dưới đây là một ví dụ về tài liệu được tổ chức độc đáo trong Facebook. Mục lục sẽ đưa chúng ta đến nơi chúng ta muốn chuyển đến trong một cú nhấp chuột.

Sửa đổi và cập nhật

Cuối cùng, hãy xem lại tài liệu về những sai sót và sửa đổi khi cần thiết hoặc bất cứ khi nào có những thay đổi quan trọng đối với sản phẩm, phần mềm hoặc thư viện.

Và tài liệu của bạn sẽ không có ích cho bất kỳ ai nếu không được cập nhật thường xuyên cùng với sản phẩm của bạn.