Xin chào, chúng tôi là BFS(Byte Freaks Studio). 🎲
Hôm nay, tôi muốn giới thiệu đến các bạn một bài viết mà Julia Evans đã đăng trên blog cá nhân vào tháng 1 vừa qua. Đó chính là câu chuyện về việc trực tiếp chỉnh sửa tài liệu chính thức (documentation) của Git.
Khi sử dụng Git, chắc hẳn đã có ít nhất một lần bạn phải khựng lại trước những thuật ngữ như object, reference, hay index. Julia cũng đã gặp phải tình huống tương tự, và cuối cùng cô ấy đã cùng đồng nghiệp Marie bắt tay vào việc trực tiếp chỉnh sửa một vài trang hướng dẫn chính thức (man page) của Git.
Quá trình tinh chỉnh các trang git add, git checkout, git push, git pull bằng cách nhận phản hồi về "những điểm gây bối rối" từ 80 độc giả thử nghiệm, cùng với những khó khăn bất ngờ trong việc viết tài liệu mã nguồn mở mà họ đã nhận ra trong quá trình đó, là những nội dung mà bất kỳ người dùng Git nào cũng sẽ thấy thú vị khi đọc.
Bản dịch nằm ở bên dưới. Nếu bạn muốn xem bản gốc, bạn có thể kiểm tra trực tiếp tại đây.
Chúc bạn đọc vui vẻ. 🎲
Mô hình dữ liệu của Git (và một số cập nhật tài liệu)
Xin chào!
Mùa thu năm ngoái, tôi đã quyết định dành thời gian để cải thiện tài liệu hướng dẫn của Git. Thông thường, khi cảm thấy tài liệu còn thiếu sót, tôi thường giải quyết bằng cách viết bài trên blog hoặc làm zine riêng. Nhưng lần này, một ý nghĩ đã nảy ra trong đầu tôi.
"Liệu có thể làm cho chính tài liệu chính thức trở nên tốt hơn một chút không?"
Vì vậy, tôi đã cùng với đồng nghiệp Marie thực hiện một số cải tiến cho tài liệu Git.
Mô hình dữ liệu cho Git
Khi xem qua tài liệu Git, tôi nhận thấy Git sử dụng các thuật ngữ như object, reference, và index rất thường xuyên. Tuy nhiên, tôi phát hiện ra rằng đang thiếu các tài liệu giải thích chính xác những thuật ngữ này có nghĩa là gì và chúng có mối quan hệ như thế nào với các khái niệm cốt lõi như commit hay branch.
Vì vậy, chúng tôi đã soạn thảo tài liệu "Mô hình dữ liệu (Data Model)" mới.
Hiện tại bạn có thể đọc tại đây, và chúng tôi dự kiến nó sẽ được đưa vào trang web chính thức của Git sau bản phát hành tiếp theo.
LƯU Ý CỦA BFS: Hiện tại đã được cập nhật trên trang web chính thức của Git.
Lý do tôi đặc biệt hài lòng với công việc này là vì việc hiểu cách Git tổ chức dữ liệu commit và nhánh đã giúp ích rất nhiều cho tôi trong việc hiểu về Git suốt một thời gian dài. Vì vậy, tôi nghĩ rằng nhất định cần có một tài liệu giải thích mô hình dữ liệu của Git một cách ngắn gọn (khoảng 1.600 từ) nhưng chính xác.
Tuy nhiên, việc đảm bảo tính chính xác khó hơn tôi tưởng. Dù đã biết cấu trúc cơ bản nhưng tôi đã học được thêm nhiều chi tiết mới trong quá trình xem xét, và do đó phải chỉnh sửa nhiều phần. Ví dụ, phần giải thích về cách lưu trữ xung đột hợp nhất (merge conflict) trong vùng đệm (staging area) cũng đã được sửa đổi.
Cải thiện tài liệu bao gồm git push, git pull, v.v.
Ngoài ra, tôi cũng đã tiến hành cải thiện phần mở đầu của một vài trang hướng dẫn chính (man page) của Git.
Lúc đầu, tôi chỉ đơn giản nghĩ rằng "hãy thử sửa theo hướng mà mình cho là tốt hơn", nhưng tôi đã sớm nhận ra rằng có một vấn đề.
"Cho dù tôi có nói rằng lời giải thích của mình tốt hơn, liệu các Git maintainer có lý do gì để tin vào điều đó không?"
Khi làm việc với tài liệu mã nguồn mở, tôi thường xuyên bắt gặp tình huống như thế này.
"Giải thích như thế này không phải sẽ rõ ràng hơn sao?"
"Không, giải thích như thế kia mới tốt hơn chứ?"
Tuy nhiên, tôi nghĩ rằng việc các chuyên gia phần mềm tranh luận với nhau về việc "cách giải thích nào dễ hiểu hơn" không mấy hiệu quả. Bởi vì những người đã sử dụng một công cụ cụ thể trong thời gian dài thường khó có thể đánh giá được những người mới bắt đầu gặp khó khăn ở điểm nào.
Vì vậy, chúng tôi muốn tìm kiếm một phương pháp dựa trên cơ sở thực tế hơn một chút.
Tìm lỗi thông qua người đọc thử
Chúng tôi đã tuyển tình nguyện viên từ Mastodon để nhờ họ đọc các tài liệu hiện có và cho biết điều gì gây nhầm lẫn hoặc những câu hỏi nào nảy sinh.
Khoảng 80 độc giả thử nghiệm đã để lại ý kiến, và tôi đã học được rất nhiều điều trong quá trình đó.
Phản hồi mà mọi người để lại rất đa dạng.
Thuật ngữ khó hiểu
pathspeclà gì vậy??referencecó nghĩa là gì? mean?Thuật ngữ
upstreamcó ý nghĩa đặc biệt gì trong Git không? have a special meaning in Git?
Ý kiến cho rằng một câu cụ thể nào đó khó hiểu
Đề xuất nội dung muốn được thêm vào
"Tôi luôn làm công việc này nên tôi hy vọng nó sẽ được bao gồm ở đây."
Chỉ ra sự mâu thuẫn giữa các tài liệu
Ở một nơi thì X có vẻ như là giá trị mặc định, nhưng ở nơi khác thì Y lại có vẻ như là giá trị mặc định.
Điều thú vị là hầu hết những người đọc thử nghiệm đều là những người đã sử dụng Git ít nhất từ 5 đến 10 năm trở lên.
Điều này thực ra lại rất tốt. Bởi vì nếu ngay cả những người đã sử dụng Git trong một thời gian dài cũng cảm thấy khó hiểu một câu văn hay thuật ngữ nào đó, thì đó chính là bằng chứng mạnh mẽ cho thấy tài liệu cần phải được sửa đổi để trở nên rõ ràng hơn.
Phương thức này, tức là
"Nếu người dùng thực tế đọc tài liệu hiện có và chỉ ra các vấn đề, chúng tôi sẽ sửa chữa những vấn đề đó"
Tôi cảm thấy cách tiếp cận này, tức là "sửa đổi vấn đề khi người dùng thực tế đọc tài liệu hiện có và chỉ ra những điểm bất cập", đã mang lại hiệu quả rất cao và tôi dự định sẽ thử áp dụng lại trong các dự án khác trong tương lai.
Bạn đã chỉnh sửa những trang hướng dẫn (manual page) nào?
Chúng tôi đã chỉnh sửa bốn trang hướng dẫn sau đây.
Đặc biệt là các thao tác git push và git pull đã mang lại sự thú vị nhất.
Ngoài việc cải thiện phần mở đầu, tôi cũng đã viết mới các nội dung sau.
upstream branchPhần giải thích về khái niệm nhánh thượng nguồn là gì(Trước đây, thực tế là nó đã không được giải thích một cách rõ ràng.)
push refspecSắp xếp lại phần giải thích vềexplanation cleanup
Khi thực hiện công việc này, tôi lại một lần nữa nhận ra việc duy trì tài liệu mã nguồn mở khó khăn đến nhường nào.
"Câu văn không chỉ cần phải rõ ràng mà đồng thời còn phải chính xác với sự thật."
Đôi khi cũng cần có sự thỏa hiệp. Ví dụ, hãy cùng xem câu văn sau đây.
git pushcó thể thất bại nếu bạn chưa thiết lậpupstreamcho nhánh hiện tại, tùy thuộc vào giá trị màpush.defaultđược thiết lập.
("현재 브랜치의upstream이 설정되지 않았다면,push.default설정에 따라git push가 실패할 수 있다.")
Lời giải thích này hơi mơ hồ. Tuy nhiên, để giải thích đầy đủ ý nghĩa chính xác của cụm từ "tùy thuộc vào cài đặt" thì sẽ phức tạp hơn rất nhiều, và chỉ riêng việc đó thôi cũng đã có thể trở thành một dự án lớn rồi.
Về quá trình đóng góp cho Git
Tôi cũng đã mất khá nhiều thời gian để hiểu được quy trình phát triển của Git.
Tôi không định giải thích tất cả ở đây. Bởi vì chỉ riêng việc đó thôi cũng có thể trở thành một bài viết riêng biệt rồi.
Thay vào đó, tôi sẽ để lại một vài ghi chú ngắn.
Git có một máy chủ Discord, và có một kênh "my first contribution" dành cho những người lần đầu đóng góp.
Tôi đã nhận được sự giúp đỡ cần thiết để bắt đầu, và mọi người đều rất thân thiện.
Tôi đã thực hiện tất cả các đóng góp thông qua GitGitGadget.
Tôi có thể sử dụng quy trình làm việc quen thuộc là GitHub Pull Request,
GitGitGadget đã giúp chuyển đổi chúng sang định dạng bản vá email (email patch) mà các nhà phát triển Git thường sử dụng.
Nhờ vậy, tôi không cần phải học cách gửi bản vá qua email theo cách mới.
Khi trả lời các đánh giá, tôi đã sử dụng trình duyệt email thông thường mà mình hay dùng (giao diện web của Fastmail).
Tôi đã ngắt dòng văn bản ở mức 80 ký tự để phù hợp với quy ước của mailing list.
Ngoài ra, kho lưu trữ danh sách gửi thư của lore.kernel.org hơi khó điều hướng. Vì vậy, tôi đã tự tạo một trình xem danh sách gửi thư Git đơn giản để giúp việc đọc các luồng thảo luận dài trở nên dễ dàng hơn.
Trong quá trình đóng góp và đánh giá, tôi đã nhận được sự giúp đỡ từ rất nhiều người. Tôi xin gửi lời cảm ơn đến Emily Shaffer, Johannes Schindelin (tác giả của GitGitGadget), Patrick Steinhardt, Ben Knoble, Junio Hamano và nhiều người khác nữa.
BFS
Điểm đáng chú ý nhất trong bài viết này là Julia đã không sửa đổi tài liệu chỉ dựa trên sự tự tin rằng "mình có thể giải thích tốt hơn". Thay vào đó, cô ấy đã thu thập phản ứng của những người dùng thực tế trước, và xác định hướng chỉnh sửa dựa trên dữ liệu đó. Việc lắng nghe tiếng nói của những người thực sự đang cảm thấy bối rối sẽ đáng tin cậy hơn nhiều so với việc hai chuyên gia tranh luận rằng "cách diễn đạt này rõ ràng hơn".
Nếu bạn vẫn luôn cảm thấy có điều gì đó chưa rõ ràng về các thuật ngữ Git dù vẫn sử dụng chúng hàng ngày, bài viết này có lẽ sẽ phần nào cho bạn thấy câu trả lời.
Trong thời gian tới, tôi dự định sẽ chọn lọc và dịch lại từng bài viết liên quan đến Git mà Julia đã đăng tải trên blog cá nhân của mình để giới thiệu đến các bạn. Có những bài viết nói về những bất tiện nhỏ mà chúng ta thường gặp khi sử dụng Git, cũng có những bài viết giúp chúng ta nhìn nhận lại những hiểu lầm về các khái niệm tưởng chừng như đã quen thuộc.
Đây là những bài viết giúp bạn hiểu sâu hơn khi xem cùng với 《How Git Works》, tôi dự định sẽ giải thích từng nội dung một nên hãy cùng mong chờ nhé. 🎲
- BFS 🎲