Các nhà phát triển Tại sao bạn không nên bỏ qua Tài liệu
Trong lĩnh vực phát triển của ứng dụng di động, ứng dụng web, ứng dụng máy tính để bàn hoặc thư viện JavaScript, tài liệu đóng vai trò quan trọng có thể quyết định thành công phát triển của phần mềm. 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à những điều ít được yêu thích nhất đối với các nhà phát triển để làm.
Không giống như viết mã (đó là những gì các nhà phát triển đã đăng ký để làm), tài liệu (mà chúng tôi không có) phải và dễ dàng được tiêu hóa bởi tất cả mọi người. Về mặt kỹ thuật, chúng ta phải dịch một ngôn ngữ máy (mã) sang ngôn ngữ dễ hiểu đối với con người, nó khó hơn âm thanh.
Mặc dù nó có thể là một gánh nặng thực sự, viết tài liệu rất quan trọng và sẽ mang lại lợi thế cho người dùng, đồng nghiệp và đặc biệt là chính bạn.
Tài liệu tốt giúp người dùng
Tài liệu giúp người đọc hiểu cách hoạt động của một mã, chắc chắn. Nhưng nhiều nhà phát triển đã sai lầm khi cho rằng người dùng phần mềm sẽ thành thạo. Do đó, tài liệu có thể là vật liệu mỏng, bỏ qua rất nhiều yếu tố cần thiết nên có ngay từ đầu. Nếu bạn am hiểu ngôn ngữ, bạn có thể tìm ra sáng kiến của riêng mình; nếu bạn không, thì bạn bị mất.
Tài liệu dành cho người dùng thường bao gồm sử dụng thực tế hoặc “làm thế nào để”. Nguyên tắc khi tạo tài liệu cho người dùng phổ thông là nó nên được rõ ràng. Sử dụng các từ thân thiện với con người được ưa thích hơn các thuật ngữ kỹ thuật hoặc biệt ngữ. Ví dụ sử dụng thực tế cũng sẽ được đánh giá rất cao.
Một thiết kế bố trí tốt cũng 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ụ hay (còn gọi là mục yêu thích của tôi) là tài liệu cho Bootstrap và WordPress ' “Những bước đầu tiên với WordPress”.
Nó cũng giúp các nhà phát triển khác
Mỗi nhà phát triển sẽ có phong cách mã hóa riêng. Nhưng, khi nói đến làm việc trong một nhóm, chúng ta thường sẽ phải chia sẻ mã với các đồng đội khác. Vì vậy, nó là điều cần thiết để có sự đồng thuận về một tiêu chuẩn để giữ tất cả mọi người trên cùng một trang. Một tài liệu được viết đúng 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 của người dùng cuối, tài liệu này thường mô tả quy trình kỹ thuật như quy ước đặt tên mã, cho biết cách xây dựng các trang cụ thể và cách API hoạt động cùng với các ví dụ mã. Thông thường chúng ta cũng sẽ phải viết tài liệu nội tuyến với mã (được gọi là bình luận) để mô tả những gì mã đang làm.
Ngoài ra, trong trường hợp bạn có thành viên mới tham gia nhóm của bạn sau này, tài liệu này có thể là một cách hiệu quả để đào tạo họ, vì vậy bạn không cần phải cung cấp cho họ mã 1 trên 1.
Thật kỳ lạ, nó cũng giúp người giải mã
Điều buồn cười về tiền mã hóa là đôi khi ngay cả chính các nhà phát triển cũng không hiểu mã mà họ đã viết. Điều này đặc biệt đúng trong trường hợp mã không được sử dụng trong nhiều tháng hoặc thậm chí nhiều năm.
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 những gì đang xảy ra trong tâm trí của họ khi họ viết các mã này. Đừng ngạc nhiên: Tôi đã từng ở trong tình huống này trước đây. Đây là đúng khi tôi chúc Tôi đã ghi lại mã của mình đúng cách.
Bằng cách ghi lại mã của bạn, bạn sẽ có thể nhanh chóng tìm thấy phần dưới cùng của mã và không phải nản lòng, tiết kiệm cho bạn rất nhiều thời gian có thể dành cho việc thay đổi.
Điều gì làm cho tài liệu tốt?
Có một số yếu tố để xây dựng một tài liệu tốt.
1. Không bao giờ giả định
Đừ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. Nó luôn luôn tốt hơn bắt đầu lại 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 và thậm chí hiển thị đánh dấu hoàn chỉnh cuối cùng sau khi thêm tất cả những thứ này, đây là một điều hiển nhiê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 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ẽ cho bạn một viễn cảnh tốt hơn trong việc tổ chức tác phẩm của riêng bạn.
2. Thực hiện theo tiêu chuẩn
Trong việc thêm tài liệu đi cùng với mã, sử dụng tiêu chuẩn dự kiến của ngôn ngữ. Luôn luôn là một ý tưởng tốt để mô tả từng chức năng, các biến, cũng như giá trị được trả về bởi chức năng. Dưới đây là một ví dụ về tài liệu nội tuyến tốt cho PHP.
/ ** * Thêm các lớp tùy chỉnh vào mảng các lớp cơ thể. * * @param mảng $ class Các lớp cho phần tử cơ thể. * @return mảng * / function body_groupes ($ class) // Thêm một lớp blog nhóm vào blog với hơn 1 tác giả được xuất bản. if (is_multi_ Author ()) $ class [] = 'nhóm-blog'; trả về các lớp $; add_filter ('body_group', 'body_groupes'); Sau đây là một vài tài liệu tham khảo để định dạng tài liệu nội tuyến với các thực tiễn tốt nhất về PHP, JavaScript và CSS:
- PHP: Tiêu chuẩn tài liệu PHP cho WordPress
- JavaScript: Sử dụngJSDoc
- 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ẽ khéo léo điền trước mã của bạn bằng tài liệu nội tuyến.
3. Yếu tố đồ họa
Sử dụng các yếu tố đồ họa, họ nói tốt hơn văn bản. Các 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 với 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 cứ điều gì có thể giúp người dùng tìm ra nơi cần thực hiện các bước mà không cần phỏng đoán.
Sau đây là một ví dụ từ ứng dụng Tháp nơi bạn có thể lấy cảm hứng từ đó. Họ giải thích một cách hiệu quả cách thức kiểm soát phiên bản hoạt động theo cách dễ chịu khiến nó dễ hiểu hơn là sử dụng các dòng lệnh văn bản đơn giản.
4. Phân chia
Bạn có thể xem xét gói một vài thứ trong tài liệu trong danh sách và bảng gạch đầu dòng vì điều này giúp nội dung dài hơn dễ quét và đọc hơn cho người dùng.
Thêm một bảng nội dung và phân chia tài liệu trong các phần dễ tiêu hóa, nhưng vẫn giữ mỗi phần có liên quan với những gì 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 đưa chúng ta đến nơi chúng ta muốn nhảy tới trong một cú nhấp chuột.
5. Sửa đổi và cập nhật
Cuối cùng, xem xét tài liệu về các lỗi và sửa đổi khi cần thiết hoặc bất cứ khi nào có thay đổi đáng kể đối với sản phẩm, phần mềm hoặc thư viện. Tài liệu của bạn sẽ không được sử dụng cho bất cứ 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.
