Bạn đang xem : cách sử dụng tính năng ghi tài liệu

Đây là phần viết của Bản trình bày. Vui lòng cung cấp phản hồi cho @ericholscher. Bạn có thể xem nguồn trên GitHub.

Cảnh trên đây ai cũng biết để kiếm sống;
những cảm xúc lẫn lộn của một trang giấy trắng.
Đầy hứng khởi, tươi mới với một khởi đầu mới.
Nhưng cũng đầy tuyệt vọng, bạn thậm chí phải bắt đầu từ đâu?

Tôi ở đây để ngăn cảnh này diễn ra.

Đây là hướng dẫn ghi lại dự án đầu tiên của bạn.
Lần đầu tiên luôn là lần khó nhất,
và tôi hy vọng hướng dẫn này sẽ giúp bạn bắt đầu con đường chân chính.
Cuối cùng,
bạn nên có một dự án sẵn sàng để phát hành công khai.

Vui lòng đọc trực tiếp tài liệu này,
hoặc đơn giản là sử dụng nó làm tài liệu tham khảo.

Tại sao viết docs

Bạn sẽ sử dụng mã của mình sau 6 tháng nữa

Mã bạn đã viết 6 tháng trước thường không thể phân biệt được với mã mà người khác đã viết.
Bạn sẽ nhìn vào một tập tin với một cảm giác tưởng nhớ khó quên.
Sau đó, một cảm giác lén lút của điềm báo,
biết rằng ai đó ít kinh nghiệm hơn, kém khôn ngoan hơn đã viết nó.

Khi bạn trải qua hành động quên mình tháo gỡ những điều hiển nhiên hoặc thông minh này vài tháng trước,
bạn sẽ bắt đầu đồng cảm với người dùng của mình.
Giá như tôi viết ra lý do tại sao tôi đã làm điều này.
Cuộc sống sẽ đơn giản hơn rất nhiều.
Tài liệu cho phép bạn chuyển mã lý do.
Phần lớn các nhận xét mã giải thích lý do tại sao,
và không phải như thế nào,
tài liệu phục vụ cùng một mục đích.

Có một cảm giác kỳ diệu xảy ra khi bạn phát hành mã của mình.
Nó xuất hiện theo nhiều cách khác nhau, nhưng nó luôn khiến bạn giống nhau.
Ai đó đang sử dụng mã của tôi ?!
Một sự pha trộn giữa kinh hoàng và phấn khích.

Tôi đã làm ra một thứ có giá trị!

Điều gì sẽ xảy ra nếu nó bị hỏng?!

Tôi là một nhà phát triển nguồn mở thực sự!

Ôi trời, ai đó đang sử dụng mã của tôi ..

Viết tài liệu tốt sẽ giúp giảm bớt một số nỗi sợ hãi này.
Rất nhiều nỗi sợ hãi này đến từ việc đưa một thứ gì đó vào thế giới.
Câu nói yêu thích của tôi về điều này là những điều dọc theo những dòng sau:

Sợ hãi là điều xảy ra khi bạn đang làm một việc quan trọng.

Nếu bạn đang làm công việc không đáng sợ,

nó không cải thiện bạn hoặc thế giới.

Chúc mừng bạn đã sợ!
Nó có nghĩa là bạn đang làm một điều gì đó quan trọng.

Bạn muốn mọi người sử dụng mã của mình

Bạn đã viết một đoạn mã,
và phát hành nó ra thế giới.
Bạn đã làm điều này bởi vì bạn nghĩ rằng những người khác có thể thấy nó hữu ích.
Tuy nhiên,
mọi người cần hiểu tại sao mã của bạn có thể hữu ích cho họ,
trước khi họ quyết định sử dụng nó.
Tài liệu cho mọi người biết rằng dự án này là dành cho họ.

Nếu mọi người không biết tại sao dự án của bạn tồn tại,

họ sẽ không sử dụng nó.

Nếu mọi người không thể tìm ra cách cài đặt mã của bạn,

họ sẽ không sử dụng nó.

Nếu mọi người không thể tìm ra cách sử dụng mã của bạn,

họ sẽ không sử dụng nó.

Có một số lượng nhỏ những người sẽ tìm kiếm nguồn và sử dụng bất kỳ mã nào ngoài đó.
Đó là một số rất nhỏ người,
so với những người sẽ sử dụng mã của bạn khi được ghi lại đúng cách.
Nếu bạn thực sự yêu thích dự án của mình,
ghi lại nó,
và cho phép người khác sử dụng nó.

Bạn muốn mọi người trợ giúp

Mã nguồn mở là điều kỳ diệu phải không?
Bạn phát hành mã,
và các mã gnomes xuất hiện và làm cho nó tốt hơn cho bạn.

Không hoàn toàn.

Có rất nhiều cách để mã nguồn mở tuyệt vời,
nhưng nó không tồn tại bên ngoài các định luật vật lý.
Bạn phải làm việc,
để hoàn thành công việc.

Bạn chỉ nhận được đóng góp sau khi bạn đã nỗ lực rất nhiều.

Bạn chỉ nhận được đóng góp sau khi có người dùng.

Bạn chỉ nhận được đóng góp sau khi có tài liệu.

Tài liệu cũng cung cấp nền tảng cho những đóng góp đầu tiên của bạn.
Rất nhiều người chưa bao giờ đóng góp trước đây,
và thay đổi tài liệu ít đáng sợ hơn nhiều so với thay đổi mã.
Nếu bạn không có tài liệu,
bạn sẽ bỏ lỡ toàn bộ lớp cộng tác viên.

Bạn muốn mã của mình tốt hơn

Bạn thực sự dễ dàng nảy ra một ý tưởng nghe có vẻ hoàn hảo,
nhưng hành động đưa từ ra giấy đòi hỏi sự chắt lọc suy nghĩ có thể không dễ dàng như vậy.

Việc viết tài liệu cải thiện thiết kế mã của bạn.
Trao đổi thông qua API của bạn và các quyết định thiết kế trên giấy cho phép bạn suy nghĩ về chúng theo cách chính thức hơn.
Một tác dụng phụ thú vị là nó cho phép mọi người đóng góp mã theo ý định ban đầu của bạn.

Bạn muốn trở thành một nhà văn giỏi hơn

Viết tài liệu là một hình thức viết khác với hầu hết mọi người.
Kỹ thuật viết là một nghệ thuật không tự nhiên mà có.
Viết tài liệu sẽ giúp bạn trở thành một người viết kỹ thuật giỏi hơn,
đó là một kỹ năng hữu ích cần có với tư cách là một lập trình viên.

Việc viết cũng trở nên dễ dàng hơn theo thời gian.
Nếu bạn không viết trong nhiều tháng,
khó hơn rất nhiều để bắt đầu viết lại.
Việc ghi chép các dự án của bạn thành tài liệu sẽ giúp bạn viết có nhịp độ hợp lý.

Bắt đầu đơn giản là cách tốt nhất để đạt được kết quả thực tế.
Tôi sẽ trình bày một con đường trải nhựa tốt để đi xuống,
và sau khi bạn có ý tưởng cơ bản,
bạn có thể mở rộng phạm vi của mình.
Các công cụ phải mạnh mẽ và dễ sử dụng.
Điều này loại bỏ những trở ngại đối với việc thực sự đưa các từ lên trang.

Các ví dụ trong tài liệu này đều hợp lệ Markdown reStructuredText .
reStructuredText khó sử dụng hơn một chút,
nhưng mạnh mẽ hơn.
Tôi khuyên bạn nên kiểm tra cả hai,
và quyết định xem bạn muốn sử dụng cách nào sau này.

Văn bản thuần túy được kiểm soát theo phiên bản

Là những lập trình viên, chúng ta đang sống trong một thế giới văn bản thuần túy.
Công cụ tài liệu của chúng tôi cũng không phải là ngoại lệ.
Chúng tôi muốn các công cụ biến văn bản thuần túy thành HTML đẹp.
Chúng tôi cũng có một số công cụ tốt nhất có sẵn để theo dõi các thay đổi đối với tệp.
Tại sao chúng ta không sử dụng những công cụ đó khi viết tài liệu?
Quy trình làm việc này mạnh mẽ và quen thuộc với các nhà phát triển.

Ví dụ cơ bản

 

Tài nguyên

---------

*

Tài liệu trực tuyến

:

http

:

//

tài liệu

.

wriethedocs

.

org

/

*

Hội nghị

:

http

:

//

conf

.

wriethedocs

.

org

/

Điều này sẽ hiển thị thành tiêu đề,
với một danh sách bên dưới nó.
Các URL sẽ được siêu liên kết tự động.
Viết thật dễ dàng,
vẫn có ý nghĩa như văn bản thuần túy,
và hiển thị thành HTML một cách độc đáo.

README

Các bước đầu tiên của bạn trong tài liệu sẽ đi vào README của bạn.
Các dịch vụ lưu trữ mã sẽ tự động hiển thị README của bạn thành HTML nếu bạn cung cấp phần mở rộng thích hợp.
Nó cũng là tương tác đầu tiên mà hầu hết người dùng sẽ có với dự án của bạn.
Vì vậy, có một README vững chắc sẽ phục vụ tốt cho dự án của bạn.

Một số người thậm chí còn đi xa đến mức bắt đầu dự án của bạn với README


Xem thêm những thông tin liên quan đến chủ đề làm thế nào để sử dụng tài liệu viết

Video 6 – 150 Câu Hỏi Lịch Sử Việt Nam Trọng Tâm | Sách Kingbooks #shorts

  • Tác giả: Nhà Sách Kingbooks
  • Ngày đăng: 2022-06-21
  • Đánh giá: 4 ⭐ ( 5257 lượt đánh giá )
  • Khớp với kết quả tìm kiếm: Video 6 – 150 Câu Hỏi Lịch Sử Việt Nam Trọng Tâm | Sách Kingbooks shorts
    -Seri video đặc biệt về Lịch Sử Việt Nam được kênh biên tập theo tiến trình lịch sử cho mọi người dễ học dễ ôn lại kiến thức theo những câu hỏi cụ thể và quan trọng.
    -Kiến thức lịch sử được kênh tổng hợp từ nhiều nguồn như sách giáo khoa, wiki, Đại Việt Sử Ký Toàn Thư, Việt Nam Sử Lược . Trong quá trình tổng hợp cũng khó tránh khỏi thiếu sót, rất mong mọi người đóng góp ý kiến để hoàn thiện .
    Mọi ý kiến đóng góp cho kênh xin gửi về : Gmail : contact@kingbooks.vn hoặc zalo : 0888896768 . Xin chân thành cảm ơn !
    =========================
    Tinh Hoa Trí Tuệ Nhân Loại !
    Nhà sách Kingbooks tuyển chọn những đầu sách hay ,có tính ứng dụng cao trong cuộc sống và công việc để phục vụ độc giả !
    Xem thêm các liên kết tại đây :
    + Website : https://kingbooks.vn
    + Fanpage : https://www.facebook.com/Kingbooks.vn
    + Ceo Kingbooks : https://letrongtan.com/
    + Gmail : letrongtan@kingbooks.vn

    -CÔNG TY TNHH KINGBOOKS
    MST: 0109560151
    Địa chỉ: Số nhà 5C, Hẻm 44/1/24, Tổ 5 – Bằng B, Phường Hoàng Liệt, Quận Hoàng Mai, Thành phố Hà Nội
    ================================

    Kính chúc mọi người luôn hăng say lao động ,học tập và làm việc !
    CEO LÊ TRỌNG TẤN : ZALO : 0888896768
    “Video được bảo hộ bản quyền các bạn không nên reup video tránh ảnh hưởng đến kênh các bạn”
    kingbooks,lichsu,lichsuVietNam,tomtatlichsu

Hướng dẫn sử dụng Google Docs – Trình xử lý văn bản

  • Tác giả: atpsoftware.vn
  • Đánh giá: 3 ⭐ ( 4977 lượt đánh giá )
  • Khớp với kết quả tìm kiếm: Hướng dẫn sử dụng Google Docs – Trình xử lý văn bản – Họ không chỉ giúp các doanh nghiệp trực tuyến tạo ra hàng tỷ đô la thông qua công cụ tìm kiếm của họ, mà họ còn – và tiếp tục – phân nhánh và tạo ra các sản phẩm khác. Hướng dẫn sử dụng Google Docs – Trình xử lý văn bản – Họ không chỉ giúp các doanh nghiệp trực tuyến tạo ra hàng tỷ đô la thông qua công cụ tìm kiếm của họ,

Làm thế nào để chia sẻ tài liệu qua phòng học Zoom? – MIMOSA2022

  • Tác giả: helpmimosa2022.misa.vn
  • Đánh giá: 4 ⭐ ( 3702 lượt đánh giá )
  • Khớp với kết quả tìm kiếm:

  • Tác giả: hpec.hmu.edu.vn
  • Đánh giá: 5 ⭐ ( 8360 lượt đánh giá )
  • Khớp với kết quả tìm kiếm:

Hướng dẫn viết tài liệu chuyên nghiệp hướng dẫn sử dụng phần mềm

  • Tác giả: sangtaotrongtamtay.vn
  • Đánh giá: 3 ⭐ ( 2274 lượt đánh giá )
  • Khớp với kết quả tìm kiếm: Xác định lý do kinh doanh cho tài liệu của bạn. Mặc dù lý do chức năng của phần mềm là để giúp người dùng hiểu cách sử dụng ứng dụng, nhưng cũng có những lý

Cách sử dụng Google Tài liệu

  • Tác giả: support.google.com
  • Đánh giá: 5 ⭐ ( 3768 lượt đánh giá )
  • Khớp với kết quả tìm kiếm: Bạn muốn khai thác thêm sức mạnh của Google Tài liệu dành cho cơ quan hoặc trường học?

Áp dụng SQL trong Excel để tạo báo cáo động

  • Tác giả: blog.hocexcel.online
  • Đánh giá: 3 ⭐ ( 7588 lượt đánh giá )
  • Khớp với kết quả tìm kiếm: Tìm hiểu ngôn ngữ SQL kết hợp với bảng tính Excel để làm báo cáo động nhanh như thế nào. Hãy sử dụng SQL cùng sợ trợ giúp của ADO trong Excel ngay bây giờ..

Xem thêm các bài viết khác thuộc chuyên mục: Kiến thức lập trình

Xem Thêm  Liên kết các trang trong HTML - cách liên kết các trang web trong html

By ads_php