Thiết kế API

Gần đến ngày cuối cùng của tuần nghỉ lễ dài, tôi miên man nghĩ đến vấn đề về estimate , dự định sáng nay viết một bài về đề tài này. Nhưng chợt nhớ đến phần thiết kế cơ bản còn thiếu – thiết kế API.
API là một mảng kiến thức rộng lớn và rất thú vị. Hầu hết các dự án dính đến client – server đều có mặt API, các phương thức cơ bản sử dụng chủ yếu trong API là POST, GET, DELETE – sự khác biệt giữa các phương thức ( POST, GET ) như thế nào , ae hỏi thánh Google nhé, bởi bài viết này chỉ tập trung đến chia sẻ thiết kế API mà thôi.
Để viết được thiết kế API , thì người thiết kế phải hiểu được mục đích sử dụng API vào làm việc gì , đòi hỏi tính security như thế nào?
Sau khi đã clear ngọn ngành rồi mới bắt tay vào thiết kế. Ví dụ, dự án vừa rồi mình đã triển khai, bài toán đưa ra phải thiết kế 2 API, một là API check account đăng nhập từ một hệ thống khác, và một API ghi log thao tác của người dùng. Do hệ thống được build trong nội bộ công ty sử dụng, nên tính security đòi hỏi ở mức trung bình – cần sử dụng một khóa token là okie. Tuy nhiên khi comfirm tài liệu với khách hàng, nội dung chỉ cần ghi log check thao tác user login /logout từ hệ thống khác thôi. Như vậy với yêu cầu này, mình có thể thiết kế một API là đủ. Bài học ở đây là có thể khách hàng thiếu sót trong việc update tài liệu, tuy nhiên mình luôn cần chủ động cập nhật kế hoạch, cách hiểu và phương thức triển khai . Việc chủ động này, thể hiện qua việc chourei hàng ngày, hoặc email báo cáo cuối ngày cho người phụ trách , đảm bảo luồng thông tin luôn được cập nhật, không bị ứ đọng ở một nút thắt nào. Ấy cũng là cách tư duy , hay phong cách làm việc của người nhật, dù cho bất kỳ tình huống nào – tồi tệ đến đâu chăng nữa, thông tin luôn phải chủ động .
Quay lại vấn đề trên, khi clear được input đầu vào, tiếp đến phải xác định được các param cần sử dụng là như thế nào, số lượng ra sao. Ví dụ làm một API check verify tài khoản thì param cần có là userID / Password là đủ, tuy nhiên một số hệ thống bảo mật cần thêm thông tin IP từ phía client truyền lên nữa…Khi request đến một link url bằng một phương thức chỉ định trước, thì server sẽ trả về kết quả đúng hoặc sai, nếu đúng thì là mã code là như thế nào, message ra sao, bala bala… mọi định nghĩa được mô tả kỹ trong bản thiết kế API.
Cụ thể một API sẽ được thiết kế như sau

Tóm lại thiết kế API tùy vào từng hệ thống sẽ có độ phức tạp khác nhau, để viết được thiết kế API là không khó, cái khó ở đây là có nắm được thông tin input rõ ràng , hiểu được mục đích sử dụng API trong hệ thống hay không mà thôi.
Mọi người có thể download , sử dụng template API bên link bên dưới.
【xxxxxxxxxxxxシステム】API一覧

Estimate dự án

Sáng nay sức hơi trâu, tiếp tục chia sẻ về cách thức triển khai estimate một dự án.
Khi nhận một dự án , hay một công đoạn nào đó , ví dụ như thiết kế, phát triển, hay thực thi test . Sau khi tìm hiểu về dự án, tính khả thi có thực hiện được hay không? Tiếp đến cần phải cung cấp cho khách hàng thấy bản schedule (WBS) triển khai công việc. Và để làm được thì đòi hỏi kỹ năng estimate.
Kỹ năng này là kỹ năng bắt buộc phải có đối với vị trí project manager. Tuy nhiên để trở thành một SE xuất sắc, thì cũng nên học tập và trau dồi kỹ năng này. Để esimate được dự án, đòi hỏi người làm estimate phải có hiểu biết về kỹ thuật, kinh nghiệm triển khai về dự án tương tự. Một số công ty mà mình đã có cơ hội được làm việc như TOSHIBA, DTS thì estimate dựa trên các chỉ số dữ liệu các dự án tương tự, việc này sẽ giảm tải, và bớt phụ thuộc vào các key member .Và số liệu này tất nhiên sẽ lấy từ các kho dữ liệu từ Redmine, Jira, hay một tool quản lý của công ty. Những công ty lớn, có quy trình triển khai phần mềm tốt đều thực thi input đầu vào rất nghiêm ngặt đảm bảo độ chính xác khá cao.
Nội dung chia sẻ sử dụng dữ liệu được chiết xuất từ các tool quản lý để estimate mình sẽ chia sẻ ở một bài viết khác, còn bài viết này sẽ hướng dẫn một cách nông dân hơn, tự tay estimate là như thế nào !
Điều kiện input là người estimate phải hiểu được công việc được giao, đã từng có kinh nghiệm thực thi công việc tương tự. Trường hợp không đảm bảo input đầu vào thì mình nghĩ nên nhờ hoặc báo cáo sếp tình trạng thực tế để có phương án dự phòng.
Kinh nghiệm để estimate là ” Chia để trị ” – công thức này áp dụng một cách triệt để trong khâu phân tích yêu cầu, cũng như việc bóc tách source, tính cost trên mỗi đơn vị nhỏ nhất.
Cụ thể dự án sắp tới, Satou giao cho mình care công việc convert, fix lỗi HTML5.
Áp dụng công thức trên, mình đã comfirm với Satou : okie HTML5 tao đã từng làm, hãy cung cấp cho tao source và tài liệu mô tả yêu cầu, để tao điều tra xem như thế nào, hẹn hôm sau tao sẽ báo kết quả. Mình chia sẻ một chút về cách thức làm việc của người Nhật, khi đưa ra đề xuất – luôn phải có thời gian comfirm khi nào trả lời. Thời gian comfirm thực tế có thể bị sai lệch so với dự định, cái mấu chốt ở đây là phải có thời gian xác nhận tình trạng công việc – người Nhật cần thế, trường hợp kết quả điều tra lâu hơn dự định , thì cần phải báo cáo tình trạng, nguyên nhân và cách xử lý càng sớm càng tốt cho người quản lý.
Quay lại nội dung estimate trên, có câu hỏi là ” tôi đã làm những gì để trả lời cho Satou về kết quả điều tra esimate vào ngày hôm sau? ”
Điều đầu tiên là tôi điều tra về tài liệu mô tả. Okie đây rồi, có một file mô tả danh sách các lỗi cú pháp HTML5 trong dự án – có 21 lỗi tất cả, tất nhiên mỗi lỗi mẹ sẽ đẻ ra một list các lỗi con, nên tất nhiên số lỗi sẽ nhiều hơn thế.
Đầu vào khá clear rồi, tiếp đến phải điều tra source. Dự án này dùng Java, vậy sử dụng eclips để deploy thôi, sau khi deploy okie. Tiếp đến , mình không quên cài thêm công cụ editor thần thánh sakura, bởi sakura có chức năng grep cực mạnh, rất nhiều option tuyệt vời.
Chia nhỏ từng lỗi trong 21 lỗi về HTML5 , nhặt từng key cho vào filter đầu vào sakura để grep . Mục đích là để tái hiện các lỗi này trong source , khi search ra kết quả lỗi , mình check ngược lại source đọc sơ qua , phán đoán xem nguyên nhân lỗi là gì. Okie đây rồi, hệ thống nó sử dụng HTML4 !
Cứ thế từng chút từng chút một, bóc tách lần lượt hết các lỗi trong list file mô tả. Kết quả đưa ra là có 4 lỗi mình không tái hiện được – warring trong email báo cáo cho Satou.
Tiếp theo, “chia để trị ” cho việc phân tích source. Các lỗi HTML5 này nằm hết trong các file JSP , đầu tiên mình sẽ đếm có bao nhiêu file JSP. Kết quả là 629 file, trả lời cho câu hỏi ” vậy cần bao nhiêu thời gian để xử lý cho một file ?” tất nhiên mỗi file sẽ có thời gian khác nhau, sự khác nhau đến từ số lượng dòng code. Okie, tiếp đến hỏi thánh Google “eclipe 行数　カウント” thánh trả lời hãy sử dụng plugin bên dưới, cùng với hướng dẫn rất chi tiết. Làm theo step by step màn hình thống kê rất chi tiết về số dòng code thực tế, số dòng comment, tổng số dòng code…, ola tuyệt vời, mình chỉ việc export ra file excel để chuẩn bị làm file estimate.
Công việc cuối cùng là căn cứ vào các lỗi mà mình đã tái hiện ở bước đầu, kết hợp với số lượng dòng code ở bước 2, ước lượng ra từng hệ số thời gian xử lý tương ứng với từng file code. Xong xuôi SUM tính tổng time, rồi tính ra cost theo ngày (人日), cost theo tháng (人月).
Việc đơn giản và hạnh phúc nhất là email báo cáo kết quả cho Satou. Tất nhiên, không quên note rõ ràng điều kiện estimate được (前提条件), 4 lỗi không tái hiện được. Và gửi file kết quả estimate điều tra !

Điều mình muốn chia sẽ ở topic này là công thức ” chia để trị ” áp dụng triệt để khi thực thi estimate. Hai là khi đưa ra bất cứ nhận định nào , thì phải dựa trên kết quả điều tra thực tế mà có !

3 bước quan trọng để trở thành BrSE ‘chuẩn Nhật’

Giao tiếp:

Đầu tiên là khâu giao tiếp. Việc trình bày một vấn đề cho khách hàng hiểu là rất quan trọng. Các bạn để ý khi người Nhật trình bày 1 vấn đề gì đó, họ cũng bắt đầu từ chỗ xuất phát, nói để cho người chưa nghe về vấn đề đó bao giờ cũng có thể hình dung ra được. Ngược lại, các kỹ sư Việt Nam thì hay có kiểu nhảy vào cái là nói đến những cái rất sâu xa, cứ như là ai cũng hiểu vấn đề mình đang nói hết rồi, chẳng có đầu có cuối gì hết. Vì vậy, khi trình bày thì các bạn cố gắng nói rõ ngữ cảnh, hoàn cảnh, tiền đề, rồi mới đi vào chi tiết. Khi bắt đầu trình bày, hãy coi như người đối diện chưa nắm được thông tin gì.

Cũng trong phần giao tiếp, việc liên lạc trước nội dung trao đổi là cần thiết. Vừa rồi, mình vừa được CC vào email của offshore gửi khách hàng, trong mail nói: “Lát nữa tôi muốn họp với bạn về anken ABC, mấy giờ bạn rảnh nhỉ? Tôi sẽ gọi sang họp qua tivi”. Tại sao bạn không dành một chút thời gian viết trong email là muốn trao đổi về vấn đề gì, để khách hàng còn chuẩn bị tài liệu, hoặc có thể phải gọi người khác có liên quan vào họp cùng, hoặc có thể khách hàng phải xin ý kiến end-users ở team khác thì mới trả lời được? Nếu không liên lạc nội dung trao đổi trước, khách hàng hoàn toàn bị động, có thể không có đủ thông tin để trả lời, để ra quyết định và khi đó sẽ mất thêm một buổi nữa mới chốt được vấn đề. Điều này sẽ làm mất thêm thời gian cho các bên.

Chúng ta, BrSE, cũng cần thống nhất ý kiến, quan điểm với offshore trước khi cần bố trí cuộc họp với khách hàng. Hai bên của FPT cần phải thống nhất toàn bộ nội dung sẽ nói trong cuộc họp, tránh trường hợp offshore nói một kiểu, BrSE lại bảo không phải thế. Ngoài ra, BrSE nên trao đổi trước với offshore để nắm được tối đa thông tin, để khi khách hàng hỏi, có thể trả lời ngay mà không cần mất thời gian quay ra xác nhận với offshore bằng tiếng Việt, để khách hàng ngồi bên cạnh như một người vừa câm vừa điếc. Mình đã chứng kiến nhiều trường hợp BrSE quay ra xác nhận với offshore cả 10-15 phút, thậm chí tranh luận gay gắt trước mặt khách hàng. Khách hàng họ chán lắm mà họ không dám nói ra đấy thôi!

Ngoài ra, khi nghe khách hàng nói, kể cả BrSE hay offshore, nếu nghe được, hãy biểu hiện ra ngoài là mình nghe được, hiểu được (gật đầu nói はい), chỗ nào không hiểu hoặc không chắc chắn, nên xác nhận lại ngay. Không nên ngồi im thin thít chỉ nghe mà không phản ứng gì, làm như thế khách hàng rất hoang mang, không hiểu nó có nghe được mình nói không, nghe được rồi có hiểu không, hiểu rồi nhưng có hiểu đúng không. Kể cả khi hiểu hết nội dung khách hàng nói, chúng ta cũng nên nhắc lại một cách tóm tắt, để khách hàng yên tâm là mình đã nắm được.

Tuy nhiên, mình cũng đã gặp những ông nghe không hiểu mà cứ はいはい và gật như bổ củi từ đầu đến cuối. Về vấn đề nghe không hiểu mà không muốn phiền khách hàng nhắc lại, mình sẽ chia sẻ ở bên dưới nhé.

Mọi người vẫn truyền nhau lời khuyên không được giấu dốt, không nghe được phải bảo khách hàng nhắc lại. Đúng với một vài lần đầu, lần nào cũng yêu cầu khách hàng nhắc lại thì họ cũng phát chán và chả muốn làm việc với mình nữa.

Vậy với những người mới sang Nhật, nghe không tốt thì phải làm sao?

Hãy sắm một cái máy ghi âm và xin phép khách hàng cho ghi âm rồi về nghe lại là tốt nhất. Nếu khách hàng không cho ghi âm vì lý do bảo mật, hãy cầm giấy bút, ghi chép lại tất cả những gì nghe được. Kể cả là chỉ mấy phiên âm romaji rời rạc, lưu lại được càng nhiều thông tin càng tốt, khi về chỗ bình tĩnh lại thì xâu chuỗi lại xem có hiểu hơn được gì không, rồi trình bày lại ý hiểu của mình cho khách hàng để confirm. Lúc confirm, trong đầu mình đã có keywords và context rồi mình sẽ dễ dàng hiểu điều khách hàng nói hơn.

Không nên nói là: tôi không hiểu anh muốn nói gì. Mà nên nói: tôi hiểu thế này có đúng không?

Khi muốn xin ý kiến khách hàng về một vấn đề gì đó, về một cách làm nào đó, trước tiên hãy tự mình suy nghĩ và đưa ra một hoặc một vài đề xuất, rồi trình bày cho khách hàng, hỏi xem với các cách làm đó thì họ có ý kiến thế nào, có ổn không… Không nên hỏi cái này làm thế nào nhỉ? Vì sao? Vì khi mình trình bày các đề xuất của bản thân, khách hàng sẽ thấy mình đã bỏ công sức tìm hiểu, họ sẽ nhiệt tình bỏ công sức ra xem xét, cho ý kiến. Không ai muốn nhiệt tình với một người không chịu suy nghĩ, lười biếng và ỷ lại.

Khi khách hàng giao việc, ví dụ thu thập thông tin của offshore để phục vụ báo cáo gì đó, không nên mải mê ngồi làm rồi nộp sản phẩm cuối cùng. Bước đầu hãy tạo ra template (biểu mẫu), xác nhận xem làm theo template đó có đúng không, rồi mới làm tiếp. Làm thế để tránh mất thời gian và công sức làm lại nếu chẳng may ta hiểu sai ý khách hàng.

Kể cả bạn ở Nhật rất lâu rồi, bạn làm cho nhiều khách hàng rồi, nhưng khi sang khách hàng mới, ở lĩnh vực mới, lại có rất nhiều từ chưa gặp bao giờ. Ngay cả với công ty khách hàng này, họ hay dùng những thuật ngữ này, nhưng với khách hàng khác họ lại hay dùng thuật ngữ khác… Khi vào khách hàng mới, công việc mới, đồng nghiệp mới, lại thêm đống từ mới nữa, nhưng cứ bình tĩnh, ai cũng thế cả thôi. Mỗi ngày thu nạp vài từ, vài tháng sẽ hiểu được hầu hết những thuật ngữ họ hay dùng với điều kiện khi gặp từ đó lần đầu không được bỏ qua, không được thờ ơ. Hãy lợi dụng bạn là người mới, bạn có quyền hỏi thật nhiều, họ sẽ tận tình giải thích. Nếu bạn bỏ qua, 3-5 tháng sau vẫn không hiểu bạn sẽ không có cơ hội hỏi ai nữa, vì bạn không còn là người mới nữa, họ sẽ không nhiệt tình như lúc bạn mới vào đâu.

Cuối cùng của phần giao tiếp mà mình muốn nói là cách liên lạc khi nghỉ phép dài ngày. Không đơn thuần chỉ là đặt cái email tự động trả lời mỗi khi có người gửi mail đến: Tôi nghỉ từ ngày… đến ngày… có việc gì hãy liên lạc qua… Họ sẽ không muốn làm phiền bạn khi bạn đang nghỉ phép, nên hãy hoàn thành công việc một cách tốt nhất trước khi nghỉ, gửi mail cho tất cả những người liên quan, liệt kê trạng thái các công việc mình đang làm, nếu có vấn đề gì nhờ ai giải quyết,… đảm bảo công việc được thông suốt dù mình không ở đó.

Viết tài liệu, email:

Thay vì tự mình viết ra email, báo cáo, hãy lưu lại các câu email, báo cáo mà cảm thấy có ích cho mình sau này vào một file MS Excel. Vì sao lại vào file excel, vì chức năng tìm kiếm trong excel có tốc độ rất cao, tìm rất nhanh. Mà excel lại cho mình phân loại, tính năng lọc (filter), điều mà MS Word không có. Khi nào cần viết về cái gì, chỉ cần search từ khóa, và bắt chước cách viết của người ta, thế là chuẩn nhất, không phải nghĩ nhiều.

Cũng giống như khi nói, khi viết, các kỹ sư Việt Nam của chúng ta còn thảm hại hơn nhiều, kỹ năng viết tài liệu không được hoặc được học một cách sơ sài ở phổ thông và đại học, dẫn đến cách viết tài liệu lủng củng, lôm côm, cẩu thả, sai sót nhiều cả về hình thức và nội dung. Vậy nên hãy dùng template có sẵn của khách hàng, cái gì trình bày được bằng sơ đồ, flow thì hãy tận dụng, vì ít phải trình bày văn vẻ rườm rà, mà lại đầy đủ nội dung, rõ ràng. Ngoài ra, không được coi thường, bỏ qua các thông tin mà các kỹ sư Việt Nam coi là không cần thiết ví dụ như lịch sử chỉnh sửa tài liệu, mục lục,… Sau khi copy paste, nhất thiết phải đọc lại từng câu từng chữ tránh lỗi copy paste – lỗi rất hay gặp của người Việt Nam mình.

Tác phong:

Khi đi vệ sinh, rửa tay xong hãy dùng khăn mùi xoa lau tay đừng vẩy tay. Chúng ta cũng nên tắm rửa sạch sẽ. Nhiều ông kỹ sư một tuần, có khi một tháng mới tắm một lần. Mùi cơ thể mình, mình không ngửi thấy đâu. Dù bạn có giỏi, có chăm chỉ đến mấy nhưng lại bẩn và hôi thì không ai muốn gần bạn đâu. Không cần phải sành điệu, bóng bẩy nhưng phải sạch sẽ. Dù công việc có bận rộn thì thỉnh thoảng cũng nên ngẩng đầu lên, nói chuyện phiếm với những người xung quanh, điều này tuy nhỏ nhưng có lợi rất nhiều cho công việc. Nếu cảm thấy không biết nói chuyện gì, hãy mang một tờ giấy quảng cáo, hoặc một bài báo đến hỏi các bác về các từ mình chưa hiểu, chỉ đơn giản thế thôi, có yêu cầu gì cao đâu. Khách hàng gọi đi họp thì không được đi tay không, khi nào cần thì mang PC theo, nếu không thì ít nhất cũng cầm theo quyển sổ và cái bút để ghi chép lại những điều quan trọng. Điều đó thể hiện sự tôn trọng với khách hàng, mình có tôn trọng họ thì họ mới tôn trọng mình.