Có bao giờ bạn nhìn chằm chằm vào màn hình, tuyệt vọng vì sếp yêu cầu gộp hai ô (merge cells) trong một bảng tài liệu, nhưng Markdown thì... chịu chết? Trong giới viết tài liệu kỹ thuật (Technical Writing), đó là khoảnh khắc "vỡ mộng" điển hình. Một bên là sự tôn sùng Markdown vì tính đơn giản, bên kia là thực tế phũ phàng khi cố gắng áp dụng nó vào các dự án nghiêm túc.

Dù Markdown đã trở nên phổ biến nhờ cú hích từ GitHub và văn hóa "Docs-as-code", nhưng khi quy mô tài liệu vượt quá một tệp README đơn lẻ, những vết nứt bắt đầu xuất hiện. Chọn sai công cụ ngay từ đầu, bạn sẽ phải trả giá bằng hàng trăm giờ tái cấu trúc (refactor) sau này. Sự phổ biến của Markdown không đồng nghĩa với việc nó là công cụ tốt nhất cho nội dung kỹ thuật phức tạp.

Sự phân mảnh của các "Hương vị" và thiếu chuẩn hóa

Vấn đề nhức nhối nhất ngăn cản Markdown trở thành một tiêu chuẩn công nghiệp thực thụ chính là sự hỗn loạn về định dạng. Phiên bản gốc do John Gruber tạo ra quá sơ sài, thậm chí còn không buồn quy định cú pháp cho bảng biểu (table).

Hậu quả của việc "mạnh ai nấy làm"

Bạn đang chơi trò may rủi với tài liệu của mình. Một đoạn text hiển thị đẹp đẽ trên nền tảng này có thể vỡ nát hoàn toàn khi chuyển sang nền tảng khác chỉ vì trình phân tích cú pháp (parser) không hiểu "tiếng lóng" của nhau. Khác với các ngôn ngữ markup được chuẩn hóa chặt chẽ, bạn không bao giờ chắc chắn 100% văn bản của mình sẽ hiển thị ra sao trên công cụ của người đọc.

Hạn chế về cấu trúc và ngữ nghĩa (Semantic Weakness)

Markdown sinh ra là để cho blog cá nhân hoặc ghi chú nhanh, không phải để gánh vác cả một hệ thống tài liệu kỹ thuật đồ sộ. Peter Conrad từng lập luận gay gắt rằng nếu Markdown có quan điểm rõ ràng hơn về cấu trúc ngữ nghĩa, nó đã không yếu thế đến vậy.

Máy móc "mù màu" với ngữ nghĩa của Markdown

Trong tài liệu kỹ thuật, sự rạch ròi là sống còn. Bạn cần phân biệt đâu là văn bản thường, đâu là cảnh báo nguy hiểm (warning), đâu là ghi chú (note). Markdown hoàn toàn bất lực trong việc gán "class" hay ngữ nghĩa cho nội dung. Với nó, mọi đoạn văn đều bình đẳng như nhau, khiến việc xử lý tự động trở nên vô vọng.

Ác mộng khi dự án phình to

Khi tài liệu phát triển từ vài trang lên hàng trăm trang, sự đơn giản của Markdown trở thành gánh nặng:

• Mù tịt về Mục lục (TOC): Markdown thuần túy không thể tự tạo mục lục động.
• Copy-paste thủ công: Không có tính năng include tệp, bạn buộc phải lặp lại nội dung ở nhiều nơi. Khi cần sửa, bạn phải sửa ở tất cả mọi nơi.
• Liên kết lỏng lẻo: Việc tham chiếu chéo (cross-references) giữa các chương hồi cực kỳ thủ công và dễ gãy đổ.

Bẫy "Văn bản thuần túy" và mớ hỗn độn HTML

Lời hứa quyến rũ nhất của Markdown là "viết như văn bản thuần túy". Nhưng thực tế, đó chỉ là lời hứa suông với các dự án kỹ thuật.

Khi sự đơn giản phản tác dụng

Markdown làm rất tốt việc in đậm hay tạo tiêu đề. Nhưng ngay khi bạn cần một thứ cơ bản như chỉnh kích thước ảnh, đổi màu chữ cảnh báo, hay gộp ô trong bảng, mặt nạ "đơn giản" rơi xuống. Bạn buộc phải nhúng mã HTML thô vào tài liệu.

Hãy xem ví dụ dưới đây. Đây là những gì bạn phải làm chỉ để có một bảng có ô gộp (colspan) - điều cực kỳ cơ bản trong tài liệu kỹ thuật:

| Tính năng | Chi tiết | Ghi chú |
|-----------|----------|---------|
| Login     | OAuth2   | ||   **Warning**
> Đừng xóa thư mục này nếu không muốn hỏng hệ thống.

WARNING: Đừng xóa thư mục này nếu không muốn hỏng hệ thống.

Chỉ một dòng code, AsciiDoc hiểu đó là cảnh báo, tự động thêm icon, tô màu và đóng khung. Không cần plugin, không cần hack HTML. Ngay cả GitHub cũng hỗ trợ AsciiDoc, chứng tỏ họ cũng thừa nhận Markdown không phải là "chìa khóa vạn năng".

Đừng thần thánh hóa Markdown

Markdown vẫn có chỗ đứng của nó, nhưng hãy dùng nó đúng mục đích:

• Các tệp README.md đơn giản.

• Viết blog cá nhân.

• Comment trên Jira/Trello.

• Tài liệu Dev-to-Dev cần tốc độ, không cần đẹp.

Nhưng với chiến lược nội dung kỹ thuật (Technical Content Strategy) dài hơi, nơi yêu cầu cấu trúc chặt chẽ và khả năng bảo trì, Markdown là một lựa chọn tồi. Đừng ép Markdown làm những việc nó không được thiết kế để làm. Việc cố chấp sử dụng nó cho các dự án lớn chỉ tạo ra nợ kỹ thuật (technical debt), buộc đội ngũ của bạn phải duy trì những tập lệnh vá víu và những đoạn mã HTML lộn xộn thay vì tập trung vào chất lượng nội dung.