Cách viết document một cách hiệu quả – P1

Chào các bạn, như bạn nào đi làm rồi thì cũng biết rằng nghề IT không chỉ làm việc với technical, với máy móc không thôi. Ngoài những công việc thuần túy là technical (coding, testing, etc) mình còn phải viết document. Tùy công ty, vị trí làm việc mà khối lượng document bạn phải viết nhiều hay ít. Tuy nhiên, tôi khá chắc là bạn cũng phải một vài đôi lần viết document. Thường khi mới vô nghề chúng ta không để ý nhiều đến việc này (vì toàn bộ thời gian là code rồi test hết rồi còn đâu). Và mỗi lần viết document, không biết các bạn có tự hỏi, mình viết document này đã tốt chưa?

Tại sao cần phải biết viết và viết được một document tốt?

Thật ra việc viết được một document tốt cũng giống như bạn code ra một feature tốt vậy. Một document tốt cần có cấu trúc bài viết hợp lý, logic, người ngoài đọc lần đầu tiên có thể hiểu ngay, giống như việc code phải logic, module rõ ràng cụ thể, dễ đọc dễ hiểu. Một tài liệu tốt không chỉ giúp cho người khác đọc vô dễ hiểu, dễ nắm bắt được ý tưởng của bạn, mà nó còn giúp ích rất nhiều cho chính bạn trong việc ghi nhớ lại những thứ cần thiết mà sau này bạn cần xem lại. Có thể ngay lúc này bạn sẽ nhớ, nhưng rồi đến một lúc nào đó khi bạn cần tìm lại một chủ đề nào đó, bạn có thể lục lại cái document bạn viết và nhớ lại rất nhanh. Ngoài ra, document tốt còn ghi điểm trong mắt đồng nghiệp và cấp trên, giúp bạn dễ dàng thăng tiến hơn công việc.

Tuy nhiên, việc code thì bạn có thể học được rất nhiều ở trong trường, trong lúc làm việc, thông qua đồng nghiệp, thông qua các trang web. Còn việc làm thể nào để viết một document hiệu quả thì sao?

Trước mắt chúng ta phải phân tích một chút về document, từ đó mới có cái nhìn tốt về việc làm sao để viết document cho hiệu quả. (Làm cái gì cũng phải phân tích, chơi lô, chơi đề người ta còn phân tích mà bạn 😀 )

Có rất nhiều loại document khác nhau: design specs, how to, bug analysis, system overview, etc và mỗi loại document lại có kiểu viết và bố cục khác nhau. Nhưng nhìn chung mục đích của document là gì? Là giúp NGƯỜI ĐỌC hiểu được hoặc có một cái nhìn tổng quan về một vấn đề nào đó. Vậy đối tượng document hướng tới là gì? Chính là NGƯỜI ĐỌC.

“Ồ tất nhiên là người đọc rồi chứ ai nữa hả bạn tôi – bạn có chơi đồ không đấy?” – Tôi có chơi nhưng chơi cafe thôi bạn.

Tôi đã đọc khá nhiều document của các bạn đồng nghiệp, kể cả mới vào làm hay là có kinh nghiệm lâu năm. Thì lỗi hay mắc phải nhất của tất cả các bạn là: document đọc rối rắm và khó hiểu. Vì sao khó hiểu? Chỉ đơn giản thôi: các bạn viết document dựa trên cái nhìn của bản thân. Ơ thế không cái nhìn của bản thân thì của thằng đồng nghiệp à? Đúng rồi bạn! Khi viết document bạn nên đặt vị trí của mình là người khác, NGƯỜI ĐỌC. Như thế có nghĩa là sao? Có nghĩa là bạn phải giả định mình là NGƯỜI KHÁC, người hoàn toàn chưa biết gì, chưa có một khái niệm nào hết về bài viết của bạn. Như thế bài viết của bạn mới dễ hiểu.

Ví dụ bạn viết một document “How to build the project”. Tôi giả định project của bạn được compile bằng Visual Studio và build tool là jom, document của bạn kiểu kiểu như sau

#Creat a folder build

mkdir build

cd build

#cmake project

cmake ..

#build project

jom all

Sau đó một người mới vô team, họ sẽ đọc document này để build, tuy nhiên đến đoạn cmake ... lại bị báo lỗi thế này

Thế là người mới vô này lại phải đi hỏi bạn tại sao bị lỗi này. Nếu may mắn, thì bạn đã gặp lỗi này và bạn sẽ nhớ ra là phải fix làm sao. À thì ra chưa gọi vcvarsall.bat. Tuy nhiên, nếu chính bạn cũng quên thì sẽ khá mất thời gian để cả 2 cùng đi tìm hiểu tại sao lại bị vậy. Lúc bạn viết document Hot to build the project này, có thể máy bạn đã có sắn môi trường như vầy rồi, hoặc bạn chỉ muốn viết ngắn gọn, nhưng với một người mới hoàn toàn chưa biết gì thì sao?

OK giờ chúng ta thử viết document trên với tâm thế là của người đọc, người chưa biết gì xem sao. Nhưng làm sao để đặt mình vô tâm thế người đọc? Tôi có biết người ta nghĩ gì đâu? Có một cách rất hay và tôi thường hay áp dụng khi viết document là tự đặt câu hỏi cho chính bản thân mình, ví dụ với document trên thì chúng ta sẽ có những câu hỏi kiểu như này

Máy của mình đã có đủ tool để build chưa? cmake thì dùng version nào? Visual Studio verison nào. Nếu run command này bị failed thì có thể failed như nào và cách fix là gì? Nếu tôi muốn build project trên Linux thì câu lệnh build như nào? etc

Các bạn thấy đó, khi mình đặt câu hỏi, mình sẽ có thể nhìn nhận được bài viết dưới góc độ của người khác, giờ document sẽ được viết lại như sau (các bạn xem thử coi có ổn hơn không? Tất nhiên tôi chỉ viết ví dụ thôi nhé có thể còn viết được tốt hơn nữa)

# Prerequisites

# Install: Visual Studio 2013, cmake version >= 3.1, QT framework version xxx, Postgresql version xxx

# Open cmd, go to the project folder, creat a folder build

cd path_to_the_project

mkdir build

cd build

# Call vcvarsall.bat for setting environment

%VS2013Tools%\vcvarsall.bat

# Make project

cmake ..

# Build

jom all

Kết

Mỗi khi bạn định viết một thứ gì đó, bạn cần đặt mình vào vị trí người đọc. Sau khi viết xong một đoạn, bạn hãy đọc thử đoạn đó và hãy suy nghĩ: nếu một người hoàn toàn chưa biết gì đọc vô đoạn này có hiểu không?