Tầm quan trọng của tài liệu đối với nhà phát triển web

Trong lĩnh vực phát triển của ứng dụng di động, web và máy tính để bàn hoặc thư viện JavaScript, tài liệu đó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 mã (đó là những gì các nhà phát triển đã đăng ký để làm), tài liệu phải được dễ dàng tiêu hóa bằng 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 một ngôn ngữ có thể hiểu được đối với con người, ngôn ngữ này khó hơn âm thanh của nó.

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.

Học lập trình: 10 quan niệm sai lầm không đúng

Học lập trình: 10 quan niệm sai lầm không đúng

Có rất nhiều quan niệm sai lầm và lầm tưởng xung quanh nghệ thuật lập trình. Nhiều người xem nó như một công việc … Đọc thêm

Tài liệu tốt giúp người dùng

Tài liệu giúp ích cho người đọc hiểu cách mã hoạt động, chắc chắn. 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.

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 thực hiện”. Quy tắc chung khi tạo tài liệu cho người dùng thông thường là nó 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ụ điển hình (hay còn gọi là mục yêu thích của tôi) là tài liệu cho Bootstrap và “Những bước đầu tiên với WordPress” của WordPress.

Nó giúp các nhà phát triển đồng nghiệp

Mỗi nhà phát triển sẽ có phong cách viết mã 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ẻ mã với các đồng đội khác. Vì vậy, điều cần thiết là có sự đồng thuận về một tiêu chuẩn để giữ cho mọi người trên cùng một trang. 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ả quy trình kỹ thuật như quy ước đặt tên mã, hiển thị 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ụ mã. Thông thường, chúng tôi cũng sẽ phải viết tài liệu cùng dòng với mã (được gọi là bình luận) để mô tả mã đang làm gì.

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ả về mặt thời gian để đào tạo họ, vì vậy bạn không cần phải cho họ thực hiện trực tiếp trên mã.

10 thói quen lập trình mà các nhà phát triển nên áp dụng

10 thói quen lập trình mà các nhà phát triển nên áp dụng

Những kết quả này có thể làm giảm sự tự tin của chúng ta nhưng trên thực tế, chúng có thể được giải quyết bằng các phương pháp phát triển thích hợp …. Đọc thêm

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

Điều buồn cười về lập trình là đôi khi ngay cả bản thân 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 các mã đã được giữ nguyên 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 đ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: Tôi đã từng ở trong trường hợp 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 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.

Điều gì tạo nên tài liệu 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:

1. Đừng bao giờ cho rằng

Đừ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 không phụ thuộc vào trình độ 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ó và thậm chí hiển thị đánh dấu cuối cùng hoàn chỉnh sau khi thêm tất cả những thứ này, đó là điều hiển nhiên.

ví dụ doc

Đ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.

2. Tuân theo tiêu chuẩn

Khi thêm tài liệu phù hợp với mã, 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 nội tuyến tốt cho 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 tuyến với các phương pháp hay nhất trong PHP, JavaScript và CSS:

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 mã của bạn với tài liệu nội tuyến.

Tiêu chuẩn mã hóa cho WordPress [Guide]

Tiêu chuẩn mã hóa cho WordPress [Guide]

Lý do mà chúng tôi có các tiêu chuẩn mã hóa (không chỉ cho WordPress) là để tạo ra một … Đọc thêm

3. 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 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 kỳ điều 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 hiệu quả cách hoạt động của kiểm soát phiên bản theo cách 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.

4. 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 để quét và đọc cho người dùng.

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.

doc ví dụ facebook
5. 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. 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.


Bạn đang xem : Tầm quan trọng của tài liệu đối với nhà phát triển web

Trả lời

Email của bạn sẽ không được hiển thị công khai. Các trường bắt buộc được đánh dấu *