Share

Viết sách với GitHub

Chia sẻ với các bạn những kinh nghiệm khi sử dụng GitHub để viết sách, viết tài liệu đúng cách.

Github vốn là một phần mềm, dịch vụ quản lý phiên bản dựa trên GIT, Và từ lâu rồi, chúng ta vẫn luôn nghĩ GitHub là một trong những công cụng tốt nhất để quản lý phiên bản cho các project phần mêm, quản lý phiên bản code với tính năng code nhóm.

Nhưng chức năng gốc của github không phải là quản lý phiên bản code, mà chỉ đơn giản là quản lý phiên bản. Nó có thể quản lý phiên bản của một cái gì đó mà content của nó có tính chất là text hoặc giống với text.

Vì vậy nó không chỉ dành cho lập trình viên, mà nó còn dành cho những ai sử dụng loại dữ liệu mà content là text hoặc giống text. Chẳng hạn như một writer với những trang sách của mình.

Viết thì cần gì ?

Chúng ta hãy thử liệt kê ra một vài câu trả lời :

  • Mục đích viết : Viết thì phải biết mình viết để làm gì chứ đúng không.
  • Lợi ích : Dù muốn dù không, cái gì viết ra cũng phải có lợi ích, không lợi ích cho mình thì là lợi ích cho người khác. Nếu không có lợi ích, thì không cần phải viết.
  • Công cụ để viết : Nhất định phải có rồi, không có công cụ thì không thể viết được gì cả, Đa số những cuộc cách mạng của loài người đều được đánh dấu bởi những công cụ lao động.

Mục đích và lợi ích là hai vấn đề chúng ta không nói ngày hôm nay, chúng ta sẽ chỉ nói về công cụ để viết bài mà thôi. Như đã nói, Khi những công cụ lao động đủ mạnh mẽ, chúng sẽ đưa ta tới mộ cuộc cách mạng. Và viết cũng vậy, từ chỗ viết trên đá, thẻ tre, trên lá và đến trên giấy, những công cụ hữu ích hơn sẽ giúp người viết làm việc dễ hơn, và những tác phẩm sẽ dễ dàng được hoàn thành hơn.

Các công cụ hỗ trợ viết

Có vô vàng các công cụ hỗ trợ việc viết bài, từ những công cụ offline có thể viết bất chấp có mạng hoặc không có mạng đến những công cụ viết online, hỗ trợ nhiều người cùng tham gia viết. Có rất nhiều những công cụ giống như vậy. Và chúng giúp ích cho chúng ta rất nhiều. Tuy nhiên, theo thời gian, quy mô các project đòi hỏi phải có nhiều người cùng viết hơn, vừa viết vừa hiệu chỉnh và nhu cầu trackback lại những phiên bản đã viết trước đó.

Từ tất cả những nhu cầu trên, các phần mềm quản lý phiên bản lại trở nên hữu ích hơn bao giờ hết. Như ta đã biết, Đối với Git, chũng ta có các tính năng như sau :

  1. Khi có mạng hoặc không có mạng đều viết được
  2. Quản lý nhiều phiên bản của trang viết, thậm chí nhiều nhánh của một quyển sách
  3. Nhiều tác giả có thể viết cùng lúc.
  4. Bài viết vừa được viết bởi tác già có thể được hiệu chỉnh ngay lập tức bởi người hiệu chỉnh.
  5. Cho phép cộng đồng góp ý sửa đổi nội dung
  6. Hỗ trợ comment.
  7. Ghi nhận công lao của cộng đồng.
  8. Hỗ trợ định dạng nội dụng bằng markdown đối với github

Thật tuyệt vời, đó là những gì chúng ta có thể nghĩ ra trước măt. Đó là những tính năng quá tuyệt vời cho việc ghi chép đúng không ?

Hãy hình dung, chúng ta có thể viết bài, đồng thời publish ngay lập tức cho đọc giả, học có thể đọc và cùng hiệu chỉnh, hoặc có nhã hứng, họ có thể fork lại và viết theo một nhánh mới với sự sáng tạo của riêng họ. Sẽ có một vài người hứng thú và cùng chí hướng với ta, ta có thể mời họ cùng viết với mình. Ở một quốc gia nào đó, sẽ có vài người dịch lại bài của chúng ta và push vào một branch riêng.

Cách viết trên GitHub

Để có thể viết trên github, việc đầu tiên bạn cần là tạo một account. Mọi việc rất đơn giản, chỉ cần click vào đây ( Join GitHub ) và tạo account như bao nhiêu website khác, thậm chí còn đơn giản hơn cả tạo account facebook.

Tạo repository

Sau khi đã có account bạn chỉ cần tạo một repository bằng cách ấn vào link này ( create a new repository ), Tại đây bạn có thể lựa chọn viết sách công khai, hoặc giữ nó riêng tư, nếu riêng tư thì bạn sẽ phải trả tiền. Hoặc nếu không có tiền, bạn có thể chuyển qua bitbucket.

create repository on github
create repository on github

 

Clone repository về máy

Bước tiếp theo bạn cần tải phần mềm Github for windows về máy nếu bạn sử dụng windows. Sau khi cài đặt xong, bạn truy cập vào trang repository mà bạn mới tạo lúc nảy và ấn vào nút “clone in Desktop” :

Clone github repository
Clone github repository

Lúc này repository của bạn sẽ được clone vào thư mục mặc định mà bạn thiết lập tring phần mềm GitHub desktop. Bạn chỉ cần truy cập vào thư mục này và bắt đầu dùng một trình soạn thảo văn bản đơn thuần nào đó để viết. Không nên sử dụng các trình soạn thảo như MS Word, vì các trình soạn thỏa này không chỉ sửa đổi nội dung, mà sau khi sửa đổi xong, chúng còn nén hết lại thành một file. Như vậy thì rất khó để diff những nội dung đã thay đổi. Vì thực ra khi viết, bạn không cần định dạng gì quá phức tạp. Nội dung là chính.

Hãy chú ý là trên github sử dụng markdown để định dạng, vì vậy bạn cần xem qua bài viết này : Write on GitHub.

Nhưng nếu bạn muốn có một trình soạn thảo sinh động hơn, bạn có thể thử StackEdit. Đây là trình soạn thảo online, trong lúc viết, bạn có thể review các định dạng.

Tạo trang readme

Trang readme là quan trọng, nó giống cover của quyển sách, là trang mà người dùng sẽ đọc đầu tiên khi họ truy cập vào repository của bạn. File này bạn nên đặt tên là readmy.md

Tại trang này bạn cũng viết hoặc dẫn link tới trang mục lục.

Các file nội dung khác, bạn nên tổ chức thành các thư mục, trong mỗi file dài nên có phần mục lục, và tên file có thể đặt với phần mở rộng là “md” hoặc “markdown”.

Sync local với server

Sau khi viết xong những chương, hoặc mục nào đó, bạn có thể commit và push lên github ngay, Mở phần mềm github for desktop lên, chọn repository ở cột bên trái và bạn sẽ thấy như sau :

cọmmit
cọmmit

Nếu bạn muốn xem lại các phiên bản viết trước, bạn có thể click vào các dòng ở cột giữa, nếu muốn trở lại phiên bản nào đó, bạn click vào dòng đó và ấn vài nút “revert”. Cuối cùng khi mọi chuyện đã xong, bạn ấn vào nút “Sync” để cập nhật lên server.

review revertion
review revertion

Các dòng màu đỏ là những dòng bị xóa đi, Các dòng được thêm mới sẽ có màu xanh.

Merge các sửa đổi của cộng đồng

Khi cộng đồng muốn sửa nội dung của bạn, họ sẽ phải fork, sau đó họ sửa và cuối cùng là request pull. Bạn sẽ kiểm tra xem những sửa đổi đó có hợp lý không, và sau đó merge với repository của bạn.

Lời kết

Bởi những tính năng đã nói ở trên mà việc viết sách trên GitHub đã trở nên rất phổ biến, hiện tại bạn có thể tìm được khá nhiều project viết lách. Dưới đây là một vài quyển sách hữu ích mà bạn có thể đọc :

Hy vọng trong thời gian sắp tới, chúng ta sẽ liệt kê vào đây một quyển sách nguồn mở của chính bạn, những người đã đọc bài viết này và nuôi cho mình một project lớn. Cảm ơn các bạn.