Tuy nhiên khi vào docs để xem thì ta thuận tiện bị choáng ngợp bởi lượng thông tin trong đó khiến ta không biết khởi đầu từ đâu, rồi làm thế nào để tìm đúng thứ mình cần, chưa kể bạn còn tự hỏi sao docs viết khó hiểu thể nhỉ, sao nó không hề dễ hiểu như những tutorial hay video trên mạng. Trong khi docs lại là nguồn tài liệu chính thống và đáng an toàn và đáng tin cậy của bất kỳ công nghệ nào. Nói vậy là để thấy tầm quan trọng của docs và sử dụng docs sao cho hiệu suất cao là một kiến thức và kỹ năng bắt buộc phải có .
Trong bài viết này, mình sẽ đi tìm hiểu và khám phá 1 số ít yếu tố xung quanh docs. Tại sao docs lại khó đọc như vậy, có cách nào để giúp ta xử dụng docs – nguồn tài liệu chính thống một cách hiệu suất cao và thuận tiện không ? Mình đã cố tìm hiểu và khám phá bằng cách Google để tìm đọc những bài viết nói về cách sử dụng docs sao cho hiệu suất cao. Bởi ai cũng biết, công nghệ tiên tiến thì biến hóa không ngừng, việc update kiến thức và kỹ năng công nghệ tiên tiến là vô cùng thiết yếu. Và kỹ năng và kiến thức học tập tra cứu docs mình nhìn nhận là vô cùng quan trọng, quan trọng hơn cả việc bạn biết nhiều công nghệ tiên tiến ra làm sao. Khi mình nâng cao năng lực sử dụng docs chính là mình đang nâng cao năng lực tự học, tự tiếp cận công nghệ tiên tiến của bản thân. Tuy nhiên mình nhận ra một điều, những bài viết hoặc tutorial dạy về một công nghệ tiên tiến đơn cử thì rất nhiều, nhưng những bài viết hướng dẫn người khác sử dụng docs hiệu suất cao ra làm sao thì chả có mấy. Do vậy mình đã thử tìm hiểu và khám phá đồng thời phối hợp với kinh nghiệm tay nghề bản thân để san sẻ cách sử dụng docs sao cho hiệu suất cao .
Mình sẽ chia bài viết làm 2 phần, trong phần 1 mình sẽ cùng nhau làm rõ khái niệm technical documentation là gì và giải thích lý do tại sao nó lại khó đọc như vậy. Còn ở phần 2 mình sẽ chia sẻ những cách mà mình tìm hiểu được để làm sao ta có thể sử dụng nguồn tài liệu này một cách hiệu quả.
Mình là dev nên cách tiếp cận có thiên hướng góc nhìn của dev đồng thời những ví dụ của mình sẽ thiên về tra cứu và sử dụng API của một framework hay library nào đó. Tuy vậy cách tiếp cận cũng sẽ tương tự như với những docs tương quan đến những công nghệ tiên tiến khác của devops hay administration .
Tóm Tắt
Technical documentation là gì?
Technical document là tài liệu học tập tra cứu dành cho developer, tester hoặc là bất kể ai cần tra cứu thông tin để hoàn toàn có thể sử dụng được một công nghệ tiên tiến, một framework, library hay một service nào đó. Có thể nói đây là nguồn tại liệu chính thống, không thiếu và đáng an toàn và đáng tin cậy nhất do chính người hoặc tổ chức triển khai làm ra công nghệ tiên tiến đó viết ra .
Ví dụ như bạn làm lập trình ASP.NET thì không hề không hề không biết đến ASP.NET Documentation của Microsoft. Trang này chứa mọi thông tin thiết yếu về công nghệ tiên tiến này cho bạn tra cứu. Và đây là một trong những document tốt, dễ tiếp cận, vừa đủ thông tin và được trình diễn vô cùng logic mà không phải docs nào cũng được như vậy .
Trang chủ của ASP.NET documentation, một trong những công nghệ có hệ thống technical documentation đồ sộ và tổ chức rất khoa học
Tại sao đọc docs lại khó hiểu như vậy
Lý do tiên phong phải kể đến là đứng trên góc nhìn người viết doc cũng rất khó để chiều được fan hâm mộ. Người đọc có trình độ kỹ thuật rất khác nhau, có người thì junior nhưng có người thì đã expert. Nếu viết quá kĩ, thì docs dài lê thê, và người có trình độ expert sẽ thấy quá nhiều thông tin không thiết yếu, nhưng nếu viết tổng quát hơn, chỉ tập trung chuyên sâu vào lý giải phần công nghệ tiên tiến của mình, những người junior hoàn toàn có thể thiếu những kỹ năng và kiến thức tương quan để hoàn toàn có thể hiểu thuận tiện .
Lấy ví dụ như việc viết hướng dẫn chuẩn bị sẵn sàng một bàn ăn cỗ ngày tết miền Bắc như sau :
- Bánh chưng
- Xôi gấc
- Giò lụa
- Thịt gà, thịt đông, thịt lợn luộc
- Dưa hành
- Canh miến nấu măng
- Canh xương nấu khoai tây cà rốt
- Chè kho
Nếu là mẹ mình vốn quen việc nấu nướng, thì khi đọc như vậy là đủ hiểu, bởi mẹ mình đã biết làm bánh chưng thế nào, làm xôi ra làm sao. Nhưng với mình, mình chẳng hiểu phải làm bánh chưng thế nào nữa, làm thế nào mà chuẩn bị sẵn sàng cỗ, mình rất cần một bản hướng dẫn cách làm bánh chưng, nếu tài liệu có luôn phần hướng dẫn làm bánh chưng thì tốt. Nhưng nếu viết vào thì sẽ có yếu tố như sau, một là bài hướng dẫn sẽ bị dài ra nhiều, chưa kể mẹ mình thấy đó là thông tin không thiết yếu, hoặc ai đó khác thì lại biết làm bánh chưng nhưng không biết làm xôi gấc, họ lại mong có hướng dẫn về việc làm xôi gấc. Hướng dẫn này chỉ tập trung chuyên sâu viết về việc sẵn sàng chuẩn bị bàn ăn ra làm sao hơn là nấu món ăn thế nào. Việc viết tài liệu kỹ thuật cũng như vậy, người đọc tiếp cận tài liệu với nền tảng kỹ năng và kiến thức và trình độ khác nhau, việc viết ra một tài liệu làm hài lòng toàn bộ là bất khả thi. Vậy nếu bạn thấy đọc docs có quá nhiều chỗ khó hiểu, đó là do bạn thiếu một số ít kỹ năng và kiến thức nền. Đây cũng là nguyên do đa phần nếu bạn đọc docs mà thấy khó hiểu. Tuy nhiên docs vốn là bách khoa toàn thư về một công nghệ tiên tiến đơn cử, kiến thức và kỹ năng là vô hạn và không ai hoàn toàn có thể biết hết, vậy nên ta cũng không cần phải biết hết toàn bộ .
Lý do thứ hai hoàn toàn có thể kể đến là bản thân docs cũng không được tốt. Người viết code hoàn toàn có thể họ rất giỏi trong việc viết ra library, framework nhưng họ lại không giỏi trong việc viết tài liệu. Thực tế viết code và viết tài liệu đòi khỏi những kĩ năng khác nhau. Hầu hết deveoper có năng lực tư duy logic, xử lý yếu tố rất tốt nhưng viết docs dễ hiểu yên cầu năng lực truyền đạt dễ hiểu, trình diễn mạch lạc và bố cục tổng quan rõ ràng trong bài viết. Các kiến thức và kỹ năng thường link với nhau rất ngặt nghèo, khi lý giải khái niệm này, thường sẽ phải link đến khái niệm kia, rồi kia nữa, nếu không có cách trình diễn mạch lạc rất dễ dẫn đến việc trình diễn lòng vòng và gây rối cho người đọc .Một lý do nữa đó là nhiều library hay tool là open source, được các developer viết vì đam mê và chia sẻ cho mọi người. Bản thân việc viết ra được các library đã tốn rất nhiều thời gian và công sức, và với những thứ không ra tiền mà chỉ để thỏa đam mê như vậy, họ không thể đầu tư thêm vào việc viết tài liệu, vậy nên mong chờ docs hoàn hảo trong trường hợp này là một điều xa xỉ. Thường họ sẽ chỉ có thể viết một cách tương đối và tổng quan để người đọc có thể nắm được overview, còn lại để hiểu kỹ đôi khi ta sẽ phải mò vào đọc code. Không phải open-source nào cũng như vậy, nhưng sẽ có nhiều docs cho open-source viết sơ sài như thế.
Như thế nào thì technical documentation được coi là tốt
Không phải docs nào cũng được trau truốt, khá đầy đủ thông tin và dễ hiểu cho mọi người. Vậy tất cả chúng ta hãy nghiên cứu và phân tích docs như thế nào được coi là tốt, thế nào là không, và từ đó sẽ tìm cách giải quyết và xử lý so với từng loại. Trước tiên nói về docs tốt, thường thì những docs loại này được viết bởi một công ty hay tổ chức triển khai, học góp vốn đầu tư tiền tài thời hạn và công sức của con người vào việc thiết kế xây dựng tài liệu. Trong nhiều công ty lớn, họ có một bộ phận technical writer với năng lực trình diễn và viết lách tốt hơn hẳn so với developer. Họ cũng hiểu về kỹ thuật và với sự trợ giúp của developer, họ sẽ viết ra những tài liệu có bố cục tổng quan trình diễn tốt, và dễ tiếp cận nhất. Dưới đây là những yếu tố mà docs cần có để giúp người dùng hoàn toàn có thể thuận tiện học tập tra cứu .
- Getting started: hay Quickstart là một phần không thể thiếu của docs. Một docs tốt nhất định phải có cái này. Khi ta muốn tìm hiểu về một công nghệ rất mới, mọi khái niệm đều lạ lẫm, mục này hướng dẫn người dùng step by step xây dựng được một demo nho nhỏ chạy được sẽ giúp ta nhanh chóng nắm được tổng quan công nghệ đó.
- Sample code: code mẫu của một project hoàn chỉnh hay những mẩu code nhỏ trong từng chuyên mục là cái cần thiết thứ hai. Nếu như nói “Trăm nghe không bằng một thấy”, thì ở đây “Trăm text không bằng một đoạn code” chạy được. Đôi khi những dòng hướng dẫn đọc thì khó hiểu và khó tưởng tượng, nhưng với một đoạn code nhỏ để ta chạy thử, sẽ giúp ta dễ hiểu hơn rất nhiều.
- API reference: API là cánh cổng giao tiếp mới máy tính, công nghệ nào cũng đi kèm với một list dài API, hệ điều hành thì có một danh sách các command line, chẳng ai có thể nhớ hết được, việc phải có một bách khoa toàn thư cho API hay command line để tra cứu khi cần là vô cùng cần thiết. Nếu docs mà không có cái này thì không hiểu làm việc với công nghệ đó kiểu gì.
- Search: với một lượng thông tin rất lớn thì đây là một chức năng không thể thiếu để người dùng có thể tra cứu kiến thức và nhanh chóng tìm được thông tin mình cần.
- Interactive documentation: Với những đoạn code snippet nhỏ, sẽ thật tiện nếu docs hỗ trợ khung edit và run trực tiếp luôn, như vậy ta đỡ mất công phải setup môi trường ở local, điều này tiết kiệm được rất nhiều thời gian và công sức cho người học.
- Blog and community: Cộng đồng người sử dụng công nghệ là vô cùng quan trọng, công nghệ hiện đại đến đâu mà không có người sử dụng cũng sớm bị đào thải. Vì vậy blog để cập nhật và chia sẻ thông tin, và trang community để mọi người có thể vào bàn luận đóng góp ý kiến là vô cùng quan trọng. Có thể điều này không có ý nghĩa với nhiều người như mình, vốn chỉ sử dụng docs để tra cứu công nghệ nhưng với cá nhân hay tổ chức phát triển công nghệ thì rất cần trong việc phát triển cộng đồng và cải tiến sản phẩm của mình.
- Một vài thứ khác nữa tuy nhỏ nhưng giúp ích rất nhiều và thể hiện sự chỉn chu và đầy đủ của docs. Ví dụ như docs được đánh số theo version giúp hỗ trợ developer tra cứu theo từng version hay docs được dịch ra nhiều ngôn ngữ khác nhau.
Ta hoàn toàn có thể nhìn vào trang chủ của ReactJS để thấy được điều này .
Docs của React hoàn toàn có thể nói là rất tốt khi có không thiếu công cụ tương hỗ developer học tập và tra cứu. Nếu chưa biết gì về React, ta hoàn toàn có thể học từ phần Get Started hoặc Tutorial. Mục Docs trên thanh navigation bar chính là nơi chứa những thông tin cụ thể về công nghệ tiên tiến, đồng thời có API Reference để ta tìm hiểu thêm. Đồng thời có khung search để ta hoàn toàn có thể tra cứu nhanh thông tin. Ngoài ra còn có những mục như blog, community, mục tra cứu theo version và những ngôn từ khác .
Kéo xuống phía dưới một chút ít, ta sẽ thấy một số ít đoạn code mẫu và có phần interractive để chạy thử .
React có docs tốt như vậy cũng không lạ bởi được tăng trưởng bởi Facebook .
Còn nếu như docs bị thiếu 1 số ít thành phần quan trọng như Get Started hay hay API Reference thì thực sự việc tiếp cận công nghệ tiên tiến sẽ có nhiều khó khăn vất vả. Tuy nhiên, ta cũng ít khi phải sử dụng đến những công nghệ tiên tiến như vậy .Kết luận
Trong bài viết này, mình đã đề cập đến vai trò quan trọng trong việc sử dụng technical documentation. Mình đã giải thích rõ technical documentation là gì, tại sao nó lại khá khó hiểu trong việc tiếp cận. Đồng thời mình cũng đã chỉ ra những dấu hiệu để nhận biết đâu là tài liệu được viết tốt và dễ sử dụng. Trong bài viết tiếp theo, mình sẽ chia sẻ kinh nghiệm của bản thân trong việc sử dụng docs. Đây cũng là một kĩ năng quan trọng trong việc cập nhật kiến thức công nghệ.
Phần 2 : Sử dụng technical documentation sao cho hiệu suất cao
Nếu bạn thấy bài viết hay, hãy san sẻ bài viết với bạn hữu nhé .
Source: https://final-blade.com
Category : Kiến thức Internet
