Bạn tìm thấy nó rồi. Một bài hướng dẫn hoàn hảo cho framework, API hoặc mô hình học máy (machine learning model) mới toanh mà bạn đang rất muốn thử. Lời văn mạch lạc, các khối code (code block) trông thật đẹp mắt. Bạn sao chép đoạn code (snippet), dán vào trình soạn thảo của mình, nhấn chạy và...
Lỗi: Undefined.
Có thể phiên bản đã cũ, thiếu một tệp cấu hình ẩn nào đó, hoặc máy tính của bạn chưa được thiết lập đúng cách. Có thể bạn đang dùng một thư viện CSS hiển thị trên trình duyệt khác hẳn so với bài hướng dẫn, hoặc một công cụ dòng lệnh không nhận diện được lệnh của bạn. Ngay khoảnh khắc đó, tài liệu hướng dẫn không còn giúp ích gì nữa, thực tế là nó còn làm công việc của bạn khó khăn hơn.
Hãy gọi đúng bản chất của nó:
Nếu tài liệu hướng dẫn không thể chạy được, nó chỉ là một tác phẩm hư cấu.
Kiểu đọc tài liệu rồi đối chiếu thủ công chỉ nên thuộc về những năm 2000. Tài liệu hiện đại không nên chỉ nằm im một chỗ và bắt bạn tự làm mọi thứ. Chúng không chỉ đơn thuần là một danh sách các hướng dẫn, mà còn là một công cụ giúp bạn vừa viết vừa kiểm thử (test) code cùng một lúc.
Dù bạn đang xây dựng một trang web đơn giản hay một dự án dữ liệu lớn (big data), tương lai của tài liệu lập trình phải mang tính tương tác, dễ dàng kiểm thử và quan trọng nhất là có thể chạy được.
Tài liệu tĩnh là tài liệu chết
Trong gần ba thập kỷ qua, tài liệu lập trình hầu như chỉ có một kiểu: bạn đọc thông tin nhưng không thể tương tác lại, chưa nói đến việc kiểm thử nó. Điều này vô tình tạo ra một khoảng cách về mặt ngữ cảnh. Mỗi lần bạn chuyển tab từ trình duyệt sang trình soạn thảo code, bạn lại mất đi một chút sự tập trung. Đến lần thứ mười bạn phải chuyển qua chuyển lại để đối chiếu hướng dẫn cài đặt, mạch làm việc của bạn đã hoàn toàn bị đứt quãng.
Tài liệu tĩnh thường gặp phải một tình trạng gọi là "tài liệu lỗi thời" (documentation rot). Chúng trở nên thiếu chính xác hoặc không còn phù hợp rất nhanh chóng. Một thư viện đã cập nhật lên phiên bản 2.0, nhưng bài hướng dẫn bạn tình cờ tìm thấy vẫn bị kẹt ở phiên bản 1.5. Bạn sao chép code, mong chờ một điều kỳ diệu, nhưng lại nhận về một loạt lỗi cú pháp (syntax error) vì một tính năng cốt lõi đã bị ngừng hỗ trợ từ sáu tháng trước.
Đối với người mới bắt đầu, điều này thật nản lòng, nó khiến họ cảm thấy mình không thuộc về thế giới công nghệ. Đối với một chuyên gia, đó chỉ là một sự lãng phí thời gian làm việc vô ích.
Chúng tôi đã tích hợp một trình soạn thảo code trực tiếp vào Coddy. Hãy trải nghiệm và dùng thử bất cứ lúc nào.
Tài liệu có thể chạy được là gì?
Hãy tưởng tượng việc thay thế những khối code màu xám tĩnh lặng đó bằng một môi trường phát triển thực tế được tích hợp ngay trong trình duyệt của bạn.
Đó chính là tài liệu có thể chạy được (runnable documentation).
Thay vì phải đoán xem một đoạn code hoạt động ra sao, bạn chỉ cần nhấn nút "Chạy" (Run) và thấy ngay kết quả chính xác. Không cần thiết lập môi trường cục bộ, cũng không gặp rắc rối khi cài đặt.
Sự khác biệt thực sự xuất hiện khi bạn bắt đầu chỉnh sửa code. Thay đổi các biến (variable). Thay đổi logic. Viết lại hàm (function). Bạn có thể kiểm thử giới hạn của công cụ và xem kết quả cập nhật theo thời gian thực, tất cả đều không cần rời khỏi trang web.
Bằng cách biến tài liệu hướng dẫn thành một lớp tương tác tự xác thực với code thực tế, toàn bộ cách thức học tập sẽ thay đổi hoàn toàn. Bạn không còn chỉ cuộn qua các hướng dẫn và tiếp thu câu chữ một cách thụ động nữa. Bạn là người làm chủ, tự mình kiểm thử các khái niệm và xây dựng sự tự tin ngay từ dòng code đầu tiên.
| Tính năng | Tài liệu tĩnh | Tài liệu có thể chạy được |
|---|---|---|
| Hành động của người dùng | Đọc và sao chép-dán | Kiểm thử và chỉnh sửa |
| Vòng phản hồi | Chậm (phải chuyển đổi giữa các ứng dụng) | Tức thì (kết quả hiển thị ngay trên trình duyệt) |
| Độ tin cậy | Thấp (thường bị lỗi thời) | Cao (được kiểm thử với code thực tế) |
| Thời gian thiết lập | Hơn 30 phút (cài đặt các thư viện phụ thuộc cục bộ) | 0 phút (chạy trên đám mây) |
| Phương pháp học | Lý thuyết | Thực hành / thực tế |
Tại sao điều này lại quan trọng với các lập trình viên
1. Tối ưu hóa quá trình làm quen và tăng tính tiện dụng
Phần tồi tệ nhất khi thử nghiệm bất kỳ công nghệ mới nào chính là giai đoạn "Hello World" ban đầu. Việc dành ra ba tiếng đồng hồ để vật lộn với môi trường cục bộ, giải quyết các phiên bản không tương thích của Python hay JavaScript, và sửa các đường dẫn môi trường bị lỗi thực sự rất mệt mỏi. Nó dập tắt mọi hứng khởi trước khi bạn kịp viết một dòng logic nào.
Tài liệu có thể chạy được sẽ xóa bỏ rào cản đó. (Tạm biệt sự mệt mỏi khi thiết lập môi trường!) Các thành viên mới trong nhóm hoặc các nhà phát triển bên ngoài có thể thực hiện các tác vụ thiết lập hoặc kiểm thử thiết yếu ngay từ cửa sổ trình duyệt. Bạn sẽ thấy được giá trị thực sự của một công cụ chỉ trong khoảng năm giây, thay vì mất nửa ngày trời.
2. Vòng phản hồi nhanh thúc đẩy sự tò mò
Khi có thể chạy code trực tiếp, các lập trình viên sẽ cảm thấy an tâm hơn để thử nghiệm. Trong một hướng dẫn tĩnh, bạn có thể tự hỏi: "Điều gì sẽ xảy ra nếu mình thay đổi chuỗi (string) này?" hoặc "Nếu mình dùng một mảng (array) khác thì sao?", nhưng bạn lại ngại chuyển đổi cửa sổ để kiểm tra thử.
Việc liên tục sao chép và dán các đoạn code qua lại làm giảm đáng kể hiệu suất làm việc. Tài liệu có thể chạy được biến sự tò mò thành một hành động chỉ với một cú nhấp chuột. Nhờ khả năng kiểm thử giới hạn của code theo thời gian thực mà không bị phân tâm, bạn sẽ nhanh chóng hiểu rõ cách thức hoạt động của công cụ đó.
3. Đơn giản hóa việc khắc phục sự cố và bảo trì
Khi code chạy được ngay trong tài liệu, điều đó chứng minh rằng logic hoạt động chính xác như những gì được quảng cáo. Vì vậy, nếu sau đó bạn đưa đoạn code đó vào máy cục bộ của mình và gặp lỗi, bạn sẽ biết ngay mình cần tìm lỗi ở đâu: vấn đề nằm ở cấu hình máy cục bộ của bạn, chứ không phải do lỗi logic trong thư viện. Điều này giúp bạn thu hẹp phạm vi tìm lỗi nhanh hơn nhiều.
Hướng tiếp cận này cũng giúp việc bảo trì dài hạn trở nên vô cùng đơn giản nhờ khả năng đồng bộ hóa và xác thực tự động trên các môi trường khác nhau. Ví dụ:
-
Python: Các mô-đun tích hợp sẵn như doctest tự động quét các chuỗi tài liệu (docstring), thực thi các đoạn code được nhúng để xác minh xem kết quả đầu ra có khớp với kết quả mong đợi hay không.
-
JavaScript: Các công cụ như JSDoc kết hợp với các framework kiểm thử hiện đại cho phép lập trình viên trích xuất và kiểm thử các ví dụ code từ tài liệu hướng dẫn, đảm bảo rằng những thay đổi nhỏ trong API không làm hỏng các tài liệu hướng dẫn công khai.
-
SQLite: Tài liệu tương tác cho phép lập trình viên chạy các truy vấn SQL trực tiếp trên một cơ sở dữ liệu thực tế ngay trong trình duyệt, xác minh tức thì hành vi của schema và kết quả truy vấn mà không cần thiết lập máy chủ cục bộ.
Tài liệu tương tác cho nhiều ngôn ngữ khác sẽ sớm được ra mắt.
Tâm lý học trong học tập và "Cảm giác chiến thắng"
Việc học đạt hiệu quả cao nhất khi chúng ta chủ động.
Hãy nghĩ về cách chúng ta học lái xe ô tô: chúng ta không chỉ học thuộc lòng sách hướng dẫn sử dụng. Chúng ta phải ngồi sau vô lăng và nhấn bàn đạp. Lập trình cũng áp dụng chính xác phương pháp này. Bằng cách cung cấp code tương tác, những người sáng tạo nội dung giúp lập trình viên xây dựng cảm nhận trực quan về cách một hệ thống vận hành ở phía sau.
Khi bạn có thể tự tay chỉnh sửa code, não bộ của bạn sẽ ngừng coi thông tin đó là lý thuyết trừu tượng. Bạn chuyển từ việc đọc về một hệ thống sang việc dự đoán hành vi của nó. Nếu bạn chỉ đơn thuần đọc một câu kỹ thuật, nó sẽ trôi tuột khỏi trí nhớ ngắn hạn của bạn chỉ trong vài phút.
Nhưng nếu bạn thay đổi một tham số, lật một cổng logic và quan sát kết quả đầu ra thay đổi, não bộ của bạn sẽ ghi nhận vòng lặp nguyên nhân - kết quả đó. Đó là cách kiến thức được khắc sâu.
Trong lập trình, những chiến thắng nhỏ đều có giá trị. Việc chạy thành công một đoạn code sẽ mang lại cảm giác thỏa mãn, giúp bạn có thêm động lực để giải quyết vấn đề tiếp theo. Tài liệu tĩnh thường dựng lên một bức tường gây nản lòng trước mắt lập trình viên, thường là một thông báo lỗi chung chung. Tài liệu có thể chạy được mang lại điều hoàn toàn ngược lại: một chiến thắng tức thì giúp bạn duy trì sự tập trung và khuyến khích bạn tiếp tục sáng tạo.
| Lợi ích | Cách nó giúp ích cho lập trình viên |
|---|---|
| Khả năng ghi nhớ | Thực hành luôn tốt hơn chỉ đọc lý thuyết để ghi nhớ. |
| Sự tự tin | Nhìn thấy code hoạt động giúp xây dựng lòng tin vào công cụ. |
| Hiệu quả | Không còn lãng phí thời gian vào các đoạn code bị lỗi. |
| Khả năng tiếp cận | Bất kỳ ai có trình duyệt đều có thể học hỏi, bất kể cấu hình máy tính của họ ra sao. |
Tương lai của ngành
Chúng ta đang chứng kiến một sự chuyển dịch trong cách thế giới công nghệ chia sẻ thông tin. Các nhà sáng tạo nền tảng lớn đang nhanh chóng loại bỏ các hướng dẫn chỉ đọc để chuyển sang các không gian làm việc tương tác và sân chơi tích hợp sẵn (built-in playground).
Cho dù đó là một nhà cung cấp dịch vụ đám mây cho phép bạn thực hiện một cuộc gọi API chỉ bằng một cú nhấp chuột, hay một framework CSS hiển thị một phần tử giao diện người dùng (UI) theo thời gian thực, mục tiêu vẫn luôn như nhau: rút ngắn khoảng cách giữa việc hiểu một khái niệm và thực thi nó về con số không.
Sách hướng dẫn sử dụng tĩnh là tàn dư của một thời kỳ mà sức mạnh tính toán còn hạn chế và các tập lệnh (script) còn hoạt động riêng lẻ. Ngày nay, chúng ta thiết kế các hệ sinh thái phức tạp và đa tầng. Những hệ thống tinh vi này đòi hỏi tài liệu kỹ thuật cũng phải phản hồi nhanh nhạy và linh hoạt như chính bản thân codebase vậy.
Hãy trình diễn, đừng chỉ nói suông
Đối với mọi lập trình viên, người viết tài liệu kỹ thuật và nhà sáng lập, thông điệp rất rõ ràng: đừng chỉ nói cho mọi người biết code của bạn hoạt động như thế nào. Hãy cho họ thấy!
Hãy để họ chạy thử.
Hãy để họ làm hỏng nó.
Hãy để họ tự sửa nó.
Khi bạn làm cho tài liệu của mình có thể chạy được, bạn đang thiết kế một quy trình làm việc hiệu quả. Bạn loại bỏ những rào cản không đáng có giữa một lập trình viên và dự án tuyệt vời tiếp theo của họ. Đã đến lúc ngừng vật lộn với các đoạn code lỗi thời và bắt đầu xây dựng theo thời gian thực. Tài liệu tương tác chính là tiêu chuẩn mới cho sự xuất sắc về mặt kỹ thuật.
Tại Coddy, phương pháp thực hành thực tế này được tích hợp vào mọi thứ chúng tôi làm. Cho dù bạn đang tìm hiểu tài liệu tương tác mới của chúng tôi hay tham gia bất kỳ khóa học ngôn ngữ tiêu chuẩn nào, bạn luôn có thể khám phá một khái niệm, xem code và kiểm tra kỹ năng của mình ngay trên nền tảng.
Vậy thì...
Share this article
About the Author
Jana Simeonovska
Content Strategist & Writer
Frequently Asked Questions
Tài liệu lập trình là gì?
Tài liệu chương trình (program documentation) là thông tin dưới dạng văn bản về một chương trình; bản thân văn bản chương trình cũng là một phần của tài liệu này. Tài liệu luôn đồng hành cùng các giai đoạn khác nhau trong quá trình tạo ra một chương trình. Có nhiều loại tài liệu khác nhau mô tả trạng thái của chương trình ở các giai đoạn phát triển khác nhau.
Tại sao tài liệu lập trình nên có thể chạy được?
Tài liệu có thể chạy được (runnable documentation), loại tài liệu chứa các ví dụ mã nguồn có thể thực thi, là vô cùng cần thiết vì nó đảm bảo các ví dụ luôn chính xác, cập nhật và hoạt động tốt, giúp tránh được tình trạng tài liệu bị "lỗi thời" (rot) thường gặp. Nó thu hẹp khoảng cách giữa phần giải thích và phần triển khai thực tế, giúp bạn có thể thử nghiệm, hiểu và tin tưởng vào mã nguồn ngay lập tức, từ đó thúc đẩy việc áp dụng và nâng cao năng suất của nhà phát triển.
Tại sao tài liệu lập trình lại quan trọng?
Tài liệu giải thích tất cả các tính năng của một dự án, hướng dẫn cách bạn làm việc với chúng, giúp hiểu rõ chức năng của dự án, đồng thời giúp giảm thời gian và chi phí tiếp nhận thành viên mới (onboarding). Hôm nay, chúng tôi sẽ cùng bạn tìm hiểu tài liệu phần mềm (software documentation) là gì, gồm những loại nào và tại sao tài liệu lại quan trọng trong phát triển phần mềm.
Các ví dụ về tài liệu là gì?
Là một hình thức quản lý và tổ chức tri thức, tài liệu có thể tồn tại dưới dạng bản in trên giấy, trực tuyến hoặc trên các phương tiện truyền thông kỹ thuật số hoặc tương tự, chẳng hạn như băng âm thanh hoặc đĩa CD. Các ví dụ về các tài liệu này bao gồm hướng dẫn sử dụng, sách trắng (white paper), trợ giúp trực tuyến và hướng dẫn tham khảo nhanh.
