Dự án Bokeh

Trang này chứa thông tin chi tiết về một dự án viết kỹ thuật được chấp nhận cho Phần Google Tài liệu.

Tóm tắt dự án

Tổ chức nguồn mở:
Hiệu ứng bokeh
Người viết nội dung kỹ thuật:
vis_verborum
Tên dự án:
Tạo, đọc, chia sẻ: Tối ưu hoá tài liệu của Bokeh
Thời lượng dự án:
Thời gian tiêu chuẩn (3 tháng)

Mô tả dự án

Tạo, đọc, chia sẻ: Tối ưu hoá tài liệu của Bokeh

1. Bản tóm tắt

Bokeh là một công cụ cực kỳ mạnh mẽ để tạo các hình ảnh trực quan tương tác dựa trên trình duyệt bằng Python. Nền tảng này có cơ sở người dùng khá lớn (502 nghìn lượt tải conda hằng tháng, 855 nghìn lượt tải PyPi) và một số lượng lớn người đóng góp (455 người đóng góp trên GitHub). Không có gì ngạc nhiên khi tài liệu phong phú của Bokeh được phát triển một cách tự nhiên. Và do đó, ở một số nơi, không nhất quán, khó tiếp cận và phức tạp.

Phần Tài liệu của Google mang đến một cơ hội đặc biệt để mọi người tập trung xem xét và chỉnh sửa cấu trúc cũng như nội dung trong tài liệu của Bokeh, đồng thời đảm bảo rằng tài liệu, các công cụ và quy trình làm việc liên quan sẽ phù hợp với tương lai.

Tôi đã viết mã và ghi lại các dự án nguồn mở bằng Python và Sphinx (gần đây nhất: PyZillow và PyPresseportal). Nhưng điều khiến tôi trở thành một người duy nhất tham gia Mùa tài liệu của Google chính là nền tảng báo chí của tôi: Tôi làm việc tại các toà soạn hơn 13 năm, với nhiều năm làm biên tập viên quản lý và ủng hộ sự thay đổi kỹ thuật số. Ngoài nhiệm vụ làm báo chí, tôi còn chịu nhiều trách nhiệm hơn trong việc thiết kế và ghi tài liệu về các công cụ kỹ thuật số mới, hướng dẫn về văn phong, cũng như đào tạo nhân viên toà soạn.

Sau khi chuyển từ Châu Âu sang Hoa Kỳ gần đây, tôi đã quyết định tìm hiểu những cách mới để kết hợp niềm đam mê giao tiếp và lập trình. Tôi thấy việc viết kỹ thuật là sự kết hợp tối ưu giữa kỹ năng và kinh nghiệm về viết lách và công nghệ. Trong đề xuất này, tôi sẽ trình bày cách sử dụng Phần tài liệu của Google để tối ưu hoá tài liệu của Bokeh: Bằng cách giúp tạo và đóng góp cho tài liệu thuận tiện hơn, giúp việc đọc tài liệu trở nên đơn giản hơn và chia sẻ thông tin trong tài liệu với người khác dễ dàng hơn.

2. Tình hình hiện tại

Tài liệu chính thức của Bokeh bao gồm các đơn vị chính sau:

  • Tài liệu thuyết trình: Hướng dẫn cài đặt, Hướng dẫn người dùng, Hướng dẫn cho nhà phát triển, Ghi chú phát hành
  • Thư viện và Bản minh hoạ (các ví dụ tương tác với mã nguồn)
  • Hướng dẫn tham khảo (tài liệu dựa trên chuỗi tài liệu)
  • Hướng dẫn (bộ sưu tập mở rộng các sổ ghi chép Jupyter, được lưu trữ trên mybinder.org)
  • Chuỗi tài liệu và trợ giúp về mô hình cho IDE
  • Ví dụ và tệp README trong kho lưu trữ dự án

Ngoài ra, có rất nhiều thông tin có sẵn trên diễn đàn hỗ trợ Bokeh và trên Stack Overflow, nơi nhà phát triển của Bokeh tích cực trả lời câu hỏi của người dùng, cũng như trên blog Medium của Bokeh.

Hầu hết các trang web tài liệu được tạo bằng Sphinx, sử dụng một số phần mở rộng Sphinx tiêu chuẩn và tuỳ chỉnh. Ví dụ: Hướng dẫn tham khảo được tạo từ các chuỗi tài liệu bằng cách sử dụng các phần mở rộng như "autodoc" và "bokeh_autodoc" tuỳ chỉnh. Giống như bản chất của tài liệu phát triển tự nhiên, tài liệu này có những điểm thừa thãi và không nhất quán.

Một trong những điều đầu tiên tôi nhận thấy khi phân tích tài liệu hiện có là thiếu nguyên tắc về văn phong rõ ràng khi viết tài liệu. Hướng dẫn cho nhà phát triển Bokeh có chứa một số hướng dẫn cơ bản. Tuy nhiên, tài liệu này không có nhiều hướng dẫn về văn phong, đặc biệt là về tài liệu ngoài chuỗi tài liệu. Do đó, các vấn đề về kiểu cách và cấu trúc khiến việc tiếp cận thông tin trong tài liệu trở nên khó khăn hơn, đặc biệt là đối với người mới tham gia.

Ví dụ:

Trang đích tài liệu của Bokeh khá ngắn và không bao gồm thông tin về tất cả các tài nguyên có sẵn (không đề cập đến thư viện chuỗi tài liệu phong phú và chức năng trợ giúp về mô hình, diễn đàn hỗ trợ, bản minh hoạ hoặc blog Medium). Điều này cũng khiến người dùng mới khó làm quen với Bokeh hơn.

3. Bàn thắng

Để khai thác hiệu quả nhất giai đoạn phát triển tài liệu kéo dài 11 tuần, tôi sẽ tập trung vào ba yếu tố chính:

3.1. Cải thiện quy trình tạo tài liệu

Hầu hết tài liệu của Bokeh đều do những cộng tác viên viết. Họ cung cấp tài liệu trong yêu cầu lấy các chức năng mới và bản sửa lỗi. Mặc dù sẽ ở một số giai đoạn phát triển tài liệu để chỉnh sửa và tái cấu trúc tài liệu hiện có, nhưng tôi sẽ nhấn mạnh việc xây dựng quy trình tạo tài liệu và duy trì tài liệu dẫn chứng cho tương lai: càng đơn giản càng tốt để cộng tác viên duy trì được tiêu chuẩn cao của tài liệu một cách nhất quán.

Tôi sẽ đảm bảo điều này bằng 2 hướng tiếp cận:

  • Tôi sẽ tạo một bộ nguyên tắc về kiểu đơn giản và thiết thực để đưa vào Hướng dẫn hiện có cho nhà phát triển. Những nguyên tắc này sẽ giải quyết vấn đề về kiểu, ngữ pháp và cấu trúc. Ngoài ra, tôi sẽ sử dụng các kênh trao đổi nội bộ như Slack để đảm bảo rằng những người đóng góp cho Bokeh đều nắm rõ các nguyên tắc về phong cách. Tôi cũng sẽ tổ chức các buổi đào tạo riêng cũng như các buổi hỏi đáp cho nhóm.
  • Tôi sẽ làm việc với nhóm nòng cốt để tìm ra một bộ công cụ tối ưu giúp quản lý chất lượng tài liệu. Bộ công cụ này sẽ được thêm vào quy trình làm việc hiện tại của Bokeh cho hoạt động PR (yêu cầu kéo dài) và CI (tích hợp liên tục). Tuỳ thuộc vào yêu cầu của nhóm, bạn có thể thêm các công cụ như pydocstyle, proselint hoặc sphinxcontrib-spelling vào bộ kiểm thử của Bokeh, thiết lập trước cam kết hoặc các thao tác trên GitHub. Tôi đã thêm một bằng chứng khả thi về khái niệm vào hành động trên GitHub của một trong những dự án nguồn mở của riêng mình.

3.2. Cải thiện khả năng đọc tài liệu

Mục tiêu của một tài liệu chất lượng là giúp người dùng hiện tại cũng như người dùng tiềm năng dễ dàng tìm thấy thông tin chính xác, đồng thời có thể sử dụng thông tin này một cách hiệu quả nhất có thể.

Các yếu tố chính cho khả năng hữu dụng của văn bản là phong cách và cấu trúc: Việc viết tài liệu theo một phong cách rõ ràng, nhất quán sẽ giúp người đọc tiếp thu thông tin nhanh chóng mà không bị phân tâm và dùng ngôn ngữ không cần thiết. Cấu trúc rõ ràng và minh bạch của tài liệu giúp bạn dễ dàng tìm thấy thông tin liên quan một cách nhanh chóng.

Tôi sẽ tập trung vào cả hai khía cạnh này, với trọng tâm là khả năng hữu dụng đối với người dùng mới. Trong đó có việc xem xét kỹ tài liệu tường thuật, với trọng tâm là Hướng dẫn người dùng. Tôi cũng sẽ kiểm tra toàn bộ trang đích của tài liệu để hướng đến các đối tượng mục tiêu rõ ràng hơn và đảm bảo mọi người dùng đều có thể nhanh chóng tìm thấy tài nguyên phù hợp.

Cũng giống như việc cải thiện hoạt động tạo tài liệu nêu trên, tôi sẽ tập trung vào việc đặt nền tảng cho các hoạt động cải tiến trong tương lai và tiếp tục là các tiêu chuẩn cao đối với tài liệu của Bokeh.

3.3. Cải thiện tính năng chia sẻ tài liệu

Ngày càng có nhiều cuộc thảo luận về Bokeh diễn ra trên các nền tảng của bên thứ ba. Nhiều nền tảng trong số này sử dụng siêu dữ liệu như OpenGraph của Facebook để cung cấp bản xem trước chi tiết của các đường liên kết. OpenGraph được sử dụng trong các dịch vụ như Facebook, Twitter, LinkedIn, Slack và iMessage. Diễn đàn Discourse của Bokeh cũng sử dụng OpenGraph để hiển thị bản xem trước đường liên kết.

Để sử dụng công nghệ này, tôi sẽ thêm siêu dữ liệu vào các trang web do Bokeh tạo bằng Nhân sư, như mô tả trong vấn đề #9792. Cách hiệu quả nhất là sử dụng tiện ích Sphinx chuyên dụng. Vài ngày trước, phiên bản đầu tiên của tiện ích Sphinx dành cho dữ liệu OpenGraph đã được xuất bản trên GitHub. Tôi sẽ sử dụng một số giai đoạn phát triển tài liệu để giúp cải thiện tiện ích này nhằm sử dụng với tài liệu của Bokeh.

Tôi cũng đã tạo bằng chứng về khái niệm mà tôi đang sử dụng thành công trong một trong các dự án nguồn mở của riêng mình, PyPresseportal. Tiện ích này tự động thu thập thông tin liên quan như tiêu đề, nội dung mô tả, hình ảnh và URL. Sau đó, hệ thống sẽ chèn thông tin này vào mã HTML được tạo Sphinx dưới dạng thẻ OpenGraph.

Bước tiếp theo khi phát triển tiện ích này là đưa ra các lệnh tuỳ chỉnh để xác định siêu dữ liệu OpenGraph theo cách thủ công (tương tự như lệnh "meta" hiện có trong tài liệu). Siêu dữ liệu được tạo tự động sẽ chỉ được dùng làm siêu dữ liệu dự phòng trong trường hợp không có dữ liệu được nhập theo cách thủ công.

Việc hỗ trợ Dữ liệu có cấu trúc phức tạp hơn nhiều, vì vậy tôi sẽ tập trung chủ yếu vào việc đưa siêu dữ liệu OpenGraph chất lượng cao vào tài liệu của Bokeh. Tất cả công việc hỗ trợ OpenGraph sẽ đồng thời đặt nền móng cho việc hỗ trợ Dữ liệu có cấu trúc.

Các thành viên của cộng đồng Sphinx và ReadTheDocs đã cho biết sự quan tâm đến việc phát triển các tiện ích cho OpenGraph và Dữ liệu có cấu trúc (ví dụ: trong các vấn đề #1758 và #5208) và tôi đảm bảo sẽ phối hợp chặt chẽ với họ.

4. Thành phẩm

Tóm lại, đây là những tài liệu mà tôi mong muốn sau khi ra mắt Phần Tài liệu:

  • Nguyên tắc về kiểu tài liệu dành cho cộng tác viên Bokeh
  • Sửa đổi quy trình PR và CI để thêm tính năng quản lý chất lượng tài liệu tự động
  • Hướng dẫn người dùng đã được chỉnh sửa và sắp xếp lại
  • Đã sửa đổi trang đích của tài liệu
  • Siêu dữ liệu OpenGraph có trong các trang web tài liệu và một tiện ích Sphinx đang hoạt động

Ngoài ra, tôi sẽ lưu một “doclog” để ghi lại hành trình của mình trong Phần Tài liệu của Google trên trang web cá nhân/Medium hoặc blog Medium của Bokeh. Đây cũng sẽ là cơ sở cho báo cáo dự án của Google. Tôi sẽ thực hiện mọi việc một cách minh bạch, dưới dạng các vấn đề trên GitHub và yêu cầu lấy dữ liệu, bất cứ khi nào có thể.

5. Lịch trình

Trước giai đoạn gắn kết cộng đồng: Tôi đã tích cực tham gia một số cuộc thảo luận về kho lưu trữ GitHub của Bokeh và đã liên hệ với Bryan Van de Ven và Pavithra Eswaramoorthy, những người cố vấn của Bokeh cho Mùa Tài liệu của Google. Tôi sẽ luôn tích cực trao đổi về Bokeh và cũng sẽ làm quen với Bokeh hơn nữa bằng cách xây dựng và xuất bản các hình ảnh trực quan.

Giai đoạn gắn kết cộng đồng (17/8 – 13/9):

  • Tìm hiểu về nhóm nòng cốt, tinh chỉnh kế hoạch dự án để trao đổi với những người cố vấn
  • Thiết lập lịch biểu và các kênh liên lạc để thường xuyên báo cáo và phản hồi với người cố vấn
  • Hãy tích cực sử dụng Slack của Bokeh để thông báo cho tất cả những người đóng góp quan tâm cho Bokeh về Mùa Tài liệu của Google cũng như mục tiêu cho giai đoạn phát triển tài liệu
  • Thu thập ý kiến phản hồi của những người đóng góp cho Bokeh để tinh chỉnh thêm kế hoạch cho giai đoạn phát triển tài liệu

Giai đoạn phát triển tài liệu

Tuần 1, 14/9 – 20/9:

  • Bắt đầu kiểm tra và chỉnh sửa tài liệu tường thuật
  • Bắt đầu soạn thảo nguyên tắc về kiểu

Tuần 2, 21/9 – 27/9:

  • Tiếp tục thao tác với các nguyên tắc về kiểu
  • Tiếp tục chỉnh sửa tài liệu tường thuật
  • Bắt đầu kiểm tra toàn bộ trang đích của tài liệu

Tuần 3, 28/9 – 4/10/10:

  • Hoàn thiện các nguyên tắc về kiểu
  • Hoàn tất trang đích của tài liệu

Tuần 4, 10/05 – 10/11:

  • Hoàn tất bước chỉnh sửa tài liệu tường thuật
  • Thảo luận với nhóm nòng cốt của Bokeh về việc tích hợp các công cụ để quản lý chất lượng tài liệu vào quy trình làm việc PR/CI

Tuần 5, 10/12 – 18/10:

  • Thiết lập buổi Hỏi và đáp với những người đóng góp cho Bokeh trên Slack để thảo luận về các nguyên tắc về phong cách, những điểm cải tiến trong tài liệu tường thuật và các quy trình làm việc PR/CI
  • Bắt đầu phát triển bằng chứng về khái niệm hiện có của tôi cho siêu dữ liệu OpenGraph thành tiện ích Sphinx có thể triển khai
  • Sửa đổi nguyên tắc về kiểu trình bày dựa trên ý kiến phản hồi trong phiên Hỏi và đáp với những người đóng góp cho Bokeh

Tuần 6, 19/10 – 25/10:

  • Bắt đầu thử nghiệm các công cụ để quản lý chất lượng tài liệu trong quy trình công việc quan hệ công chúng và CI
  • Tiếp tục phát triển tiện ích Sphinx cho siêu dữ liệu

Tuần 7, 26/10 – 11/11:

  • Thử nghiệm tiện ích Sphinx
  • Phiên hỏi đáp thứ hai với những người đóng góp cho Bokeh trên Slack
  • Sửa đổi nội dung cung cấp dựa trên ý kiến phản hồi trong phiên Hỏi và đáp thứ hai

Tuần 8, 2/11 – 8/11:

  • Triển khai tiện ích Sphinx và xuất bản tài liệu tường thuật cải tiến cũng như trang đích tài liệu

Tuần 9, 11/09 – 15/11:

  • Triển khai các công cụ quản lý chất lượng tài liệu vào quy trình làm việc của bộ phận quan hệ công chúng và CI
  • Cập nhật và phát hành Hướng dẫn cho nhà phát triển để bổ sung các nguyên tắc về kiểu cũng như nội dung bổ sung về quy trình công việc PR và CI

Tuần 10, 16/11 – 22/11:

  • Hoàn tất các công việc còn lại

Tuần 11, 23/11 – 29/11:

  • Bắt đầu viết báo cáo dự án
  • Bắt đầu viết đánh giá dự án

Giai đoạn hoàn thiện dự án

Tuần 12, 30/11 – 5/12:

  • Hoàn tất và gửi báo cáo dự án

Tuần 13, 12/03 – 12/10:

  • Hoàn tất và gửi đánh giá dự án

Sau khi kết thúc Phần Tài liệu của Google:

  • Tôi hy vọng sẽ tiếp tục tham gia vào quá trình phát triển Bokeh và tiếp tục làm việc với các tài liệu của Bokeh.
  • Tôi dự định tiếp tục phát triển tiện ích Sphinx cho siêu dữ liệu OpenGraph/Dữ liệu có cấu trúc.
  • Tôi hy vọng có thể vận dụng kiến thức chuyên môn về báo chí và mạng lưới hiện có của mình để quảng bá Bokeh như một công cụ trong ngành báo chí dữ liệu. Ví dụ: bằng cách viết về Bokeh dành cho một đối tượng báo chí hoặc bằng cách tổ chức các buổi nói chuyện tại hội nghị về việc sử dụng Bokeh trong bối cảnh báo chí.

6. Giới thiệu về bản thân tôi

Ban đầu, tôi là nhà báo, có kinh nghiệm về tin tức truyền hình, trực tuyến và đài phát thanh. Với vai trò biên tập viên quản lý và phóng viên trong lĩnh vực truyền hình và tin tức kỹ thuật số, tôi đã có nhiều năm kinh nghiệm viết và chỉnh sửa. Đồng thời, tôi đã tham gia một số dự án thúc đẩy quá trình chuyển đổi số và tự động hoá. Tôi đã viết rất nhiều hướng dẫn về các công cụ và quy trình làm việc kỹ thuật số, cũng như hướng dẫn về văn phong và chiến lược truyền thông cho các thương hiệu tin tức kỹ thuật số. Tôi cũng đã đào tạo các thành viên trong nhóm về cách sử dụng các công cụ đó.

Tôi luôn bị thu hút bởi điểm giao thoa giữa truyền thông và công nghệ. Một thế giới hoàn toàn mới mở ra với tôi khi tôi học cách lập trình bằng Python: Ví dụ như tôi có thể phân tích và trực quan hoá dữ liệu cho ngành báo chí dữ liệu. Việc học cách lập trình cũng cho phép tôi chủ động hợp tác với các kỹ sư phần mềm để phát triển các công cụ kỹ thuật số cho quy trình làm việc tại toà soạn.

Rất tiếc, các hướng dẫn và tài liệu mà tôi đã viết ở công việc trước đây không được công khai. Do đó, hiện tôi đang tập trung vào việc tham gia nhiều hơn vào các dự án nguồn mở (xem ví dụ dưới đây). Tôi đã viết nội dung kỹ thuật dựa trên các quy tắc lập trình, chẳng hạn như hướng dẫn quy tắc lập trình dành cho nhà phát triển của Google và hướng dẫn quy tắc lập trình của Microsoft. Tôi thường dùng GitHub, Slack và Linux. Tôi đã và đang viết tài liệu tường thuật cũng như chuỗi tài liệu và gợi ý nhập bằng cách sử dụng các công cụ như Sphinx, Mypy và Sphinx autodoc.

Tôi hiện đang làm việc tự do. Lịch trình của tôi mang đến sự linh hoạt cần thiết để làm việc trên các tài liệu của Bokeh khoảng 25 giờ mỗi tuần trong giai đoạn phát triển tài liệu. Tôi làm việc ở múi giờ Thái Bình Dương nhưng rất sẵn lòng đáp ứng lịch trình và nhu cầu của nhóm.

7. Ví dụ gần đây về tài liệu nguồn mở

  • PyZillow: PyZillow là một trình bao bọc Python cho API của trang web bất động sản Zillow.com. Ngoài việc cung cấp một số mã và đóng vai trò là một trong những trình duy trì mã, tôi đã viết tài liệu đầy đủ. Tôi đã sử dụng Sphinx cho tài liệu tường thuật cũng như tài liệu tham khảo cho học phần. Tôi đã tạo tài liệu tham khảo mô-đun với phần mở rộng Sphinx autodoc, dựa trên các chuỗi tài liệu mà tôi đã thêm vào mã.

  • PyPresseportal: PyPressecổng vào là một trình bao bọc Python cho API của trang web pressecổng.de. Trang web pressecổng.de là một trong những nhà phân phối thông cáo báo chí và thông báo về quan hệ nhà đầu tư lớn nhất ở Đức. Ví dụ: hầu hết tất cả cảnh sát và sở cứu hoả đều sử dụng dịch vụ này để phân phối các thông cáo báo chí. Sau nhiều năm sử dụng API trong vai trò một nhà báo, tôi quyết định phát triển một giao diện Python để truy cập vào nguồn tài nguyên dữ liệu đa dạng của trang web dưới dạng các đối tượng Python. Tôi đã viết mã đó và toàn bộ tài liệu dựa trên Sphinx.