Dự án Bokeh

Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.

Tóm tắt dự án

Tổ chức nguồn mở:
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
Độ dài dự án:
Thời hạn 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 hình ảnh trực quan tương tác, dựa trên trình duyệt bằng Python. Conda có một cơ sở người dùng khá lớn (502 nghìn lượt tải conda xuống mỗi tháng, 855 nghìn lượt tải PyPi xuống) và một số lượng lớn cộng tác viên (455 cộng tác viên trên GitHub). Không có gì đáng 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. Do đó, ở một số nơi, các tệp này không nhất quán, khó truy cập và phức tạp.

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

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

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ê của mình với việc giao tiếp và lập trình. Tôi nhận thấy rằng việc viết tài liệu kỹ thuật là sự kết hợp tối ưu giữa các kỹ năng và kinh nghiệm của tôi trong lĩnh vực viết lách và công nghệ. Trong đề xuất này, tôi sẽ trình bày cách tôi sẽ sử dụng Chương trình Tài liệu của Google để tối ưu hoá tài liệu của Bokeh: Bằng cách giúp việc tạo và đóng góp vào tài liệu trở nên thuận tiện hơn, giúp việc đọc tài liệu trở nên đơn giản hơn và giúp việc chia sẻ thông tin trong tài liệu với người khác trở nên 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 phần chính sau:

  • Tài liệu dạng văn bản: Hướng dẫn cài đặt, Hướng dẫn sử dụng, Hướng dẫn dành 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 docstring)
  • Hướng dẫn (bộ sưu tập sổ tay Jupyter phong phú, đượ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, bạn có thể tìm thấy nhiều thông tin trên diễn đàn hỗ trợ Bokeh và trên Stack Overflow, nơi nhà phát triển của Bokeh chủ động 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 đều được tạo bằng Sphinx, sử dụng một số phần mở rộng chuẩn và tuỳ chỉnh của Sphinx. Ví dụ: Hướng dẫn tham khảo được tạo từ docstring, sử dụng các tiện ích như "autodoc" và "bokeh_autodoc" tuỳ chỉnh. Cũng như bản chất của tài liệu phát triển một cách tự nhiên, tài liệu này chứa nhiều nội dung thừa 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 rõ ràng về cách viết tài liệu. Hướng dẫn dành cho nhà phát triển Bokeh có một số hướng dẫn cơ bản. Tuy nhiên, tài liệu này không chứa nhiều hướng dẫn về kiểu, đặc biệt là về tài liệu ngoài docstring. Do đó, các vấn đề về văn phong 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.

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ả tài nguyên có sẵn (không đề cập đến thư viện rộng lớn về docstring và các hàm trợ giúp 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ó bắt đầu sử dụng Bokeh hơn.

3. Bàn thắng

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

3.1. Cải thiện việc tạo tài liệu

Hầu hết tài liệu của Bokeh đều do các cộng tác viên viết, trong đó có tài liệu trong các yêu cầu kéo về các chức năng mới và bản sửa lỗi. Mặc dù sẽ trải qua 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 tạo quy trình tạo và duy trì tài liệu trong tương lai: Người đóng góp nên dễ dàng duy trì tiêu chuẩn nhất quán về tài liệu cao.

Tôi sẽ đảm bảo điều này bằng hai phương pháp:

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

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

Mục tiêu của tài liệu chất lượng là giúp người dùng hiện tại và người dùng tiềm năng dễ dàng tìm thấy thông tin chính xác và 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 đối với khả năng hữu dụng của văn bản là văn phong và cấu trúc: Viết tài liệu theo phong cách rõ ràng, nhất quán cho phép người đọc nhanh chóng nắm bắt thông tin mà không bị phân tâm và sử dụng ngôn từ không cần thiết. Cấu trúc tài liệu rõ ràng và đơn giản 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 đó, trong đó nhấn mạnh vào khả năng hữu dụng cho người dùng mới. Quy trình này sẽ bao gồm việc xem xét kỹ lưỡng tài liệu tường thuật, tập trung vào Hướng dẫn sử dụng. Tôi cũng sẽ cải tiến trang đích của tài liệu để giải quyết rõ ràng hơn các đối tượng mục tiêu khác nhau 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.

Tương tự như việc cải thiện khả nă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 những điểm cải tiến trong tương lai, cũng như không ngừng đặt ra 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 trên các nền tảng 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 để đưa vào bản xem trước có nhiều nội dung của các đường liên kết. OpenGraph được các dịch vụ như Facebook, Twitter, LinkedIn, Slack và iMessage sử dụng. 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 Sphinx tạo của Bokeh, như mô tả trong vấn đề #9792. Cách hiệu quả nhất là sử dụng một 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 cho dữ liệu OpenGraph đã được phát hành trên GitHub. Tôi sẽ sử dụng một số giai đoạn phát triển tài liệu để 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 một bản minh chứng 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 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 đó, trình thu thập thông tin này sẽ chèn thông tin này vào mã HTML do Sphinx tạo dưới dạng thẻ OpenGraph.

Bước tiếp theo trong quá trình phát triển tiện ích này là giới thiệu 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ư các lệnh "meta" hiện có của docutil). Siêu dữ liệu được tạo tự động sẽ chỉ được dùng làm phương án 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, nên tôi sẽ tập trung chủ yếu vào việc thêm 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 cũng sẽ đặt nền tả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 đã bày 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 sẽ đảm bảo làm việc chặt chẽ với họ.

4. Thành phẩm

Tóm lại, sau đây là những nội dung mà tôi dự kiến sẽ ra mắt trong Mùa Tài liệu:

  • Nguyên tắc về phong cách tài liệu dành cho cộng tác viên Bokeh
  • Sửa đổi quy trình PR và CI để bao gồm cả việc kiểm soát chất lượng tài liệu tự động
  • Chỉnh sửa và tái cấu trúc Hướng dẫn sử dụng
  • Trang đích của tài liệu đã sửa đổi
  • 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ẽ viết một "doclog" (nhật ký tài liệu) để ghi lại hành trình của mình trong chương trình Season of Docs 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ở để Google lập báo cáo dự án. Tôi sẽ thực hiện tất cả công 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. Dòng thời gian

Trước giai đoạn gắn kết cộng đồng: Tôi tích cực tham gia vào 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, cố vấn của Bokeh cho Season of Tài liệu của Google. Tôi sẽ tiếp tục tham gia cuộc trò chuyện về Bokeh và cũng sẽ làm quen hơn với Bokeh bằng cách tạo và xuất bản hình ảnh trực quan.

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

  • Tìm hiểu nhóm nòng cốt, điều chỉnh kế hoạch dự án để trao đổi với các cố vấn
  • Thiết lập lịch biểu và kênh liên lạc để báo cáo và phản hồi thường xuyên với người cố vấn
  • Chủ động trên Slack của Bokeh để thông báo cho tất cả những người đóng góp Bokeh quan tâm đến Mùa Tài liệu của Google và mục tiêu của giai đoạn này 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 làm theo nguyên tắc về phong cách
  • Tiếp tục chỉnh sửa tài liệu tường thuật
  • Bắt đầu cải tiến trang đích của tài liệu

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

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

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

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

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

  • Tổ chức phiên Hỏi và đáp với cộng tác viên Bokeh trên Slack để thảo luận về nguyên tắc văn phong, những điểm cải tiến đối với tài liệu tường thuật và quy trình làm việc cho quan hệ công chúng (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 một tiện ích Sphinx có thể triển khai
  • Sửa đổi nguyên tắc về kiểu dựa trên ý kiến phản hồi từ phiên hỏi đáp với các cộng tác viên của Bokeh

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

  • Bắt đầu thử nghiệm các công cụ kiểm soát chất lượng tài liệu trong quy trình làm việc của PR 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 – 01/11:

  • Kiểm thử tiện ích Sphinx
  • Buổi hỏi đáp thứ hai với các cộng tác viên của Bokeh trên Slack
  • Sửa đổi nội dung cần 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à phát hành tài liệu tường thuật và trang đích tài liệu được cải thiện

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

  • Triển khai các công cụ kiểm soát chất lượng tài liệu vào quy trình công việc PR và CI
  • Cập nhật và xuất bản Hướng dẫn cho nhà phát triển để bổ sung nguyên tắc về văn phong cũng như bổ sung 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 phần đánh giá dự án

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

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

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

Tuần 13, từ ngày 3/12 đến ngày 10/12:

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

Sau khi chương trình Mùa Tài liệu của Google kết thúc:

  • Tôi hy vọng vẫn được tham gia vào quá trình phát triển Bokeh và tiếp tục làm việc trên 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 muốn dùng kiến thức nền tảng 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 đối tượng là nhà báo hoặc bằng cách tổ chức các cuộc 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 là một nhà báo, có kinh nghiệm làm tin tức trên truyền hình, trực tuyến và đài phát thanh. Với nhiều năm kinh nghiệm làm biên tập viên quản lý và phóng viên trong lĩnh vực tin tức truyền hình và kỹ thuật số, tôi đã có kinh nghiệm viết và biên tập. Đồng thời, tôi cũng làm việc trên một số dự án thúc đẩy quá trình chuyển đổi kỹ thuật số và tự động hoá. Tôi đã viết nhiều sách 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ề phong cách 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 sự 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 cho tôi khi tôi học lập trình bằng Python: Ví dụ: tôi có thể phân tích và trực quan hoá dữ liệu cho báo chí dữ liệu. Việc học lập trình cũng giúp tôi có thể chủ động làm việc cùng 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 của phòng tin.

Rất tiếc là các tài liệu và hướng dẫn mà tôi viết tại công việc trước đây đều không công khai. Do đó, tôi hiện đ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ụ bên dưới). Tôi đã dựa vào các hướng dẫn về văn phong như hướng dẫn về văn phong viết tài liệu cho nhà phát triển của Google và hướng dẫn về văn phong của Microsoft để viết nội dung kỹ thuật. Tôi thường xuyên sử dụng GitHub, Slack và Linux. Tôi đã và đang viết tài liệu kể chuyện cũng như các chuỗi tài liệu và gợi ý về kiểu, bằ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 cho phép tôi làm việc linh hoạt cần thiết trên tài liệu của Bokeh trong 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 theo Múi giờ Thái Bình Dương nhưng sẵn sà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 người duy trì mã, tôi đã viết tài liệu hoàn chỉnh. 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 về mô-đun. Tôi đã tạo tệp tham chiếu mô-đun bằng tiện ích autodoc của Sphinx, dựa trên các docstring mà tôi đã thêm vào mã.

  • PyPresseportal: PyPresseportal là một trình bao bọc Python cho API của trang web presseportal.de. Trang web presseportal.de là một trong những nhà phân phối thông cáo báo chí và thông báo quan hệ với nhà đầu tư lớn nhất ở Đức. Ví dụ: hầu hết các sở cảnh sát và cứu hỏa đều sử dụng dịch vụ này để phân phối thông cáo báo chí. Sau khi sử dụng API trong nhiều năm với tư cách là 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 các tài nguyên dữ liệu phong phú của trang web dưới dạng đối tượng Python. Tôi đã viết mã và toàn bộ tài liệu dựa trên Sphinx.