Dự án điện tử

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ở:

Người điện

Tác giả kỹ thuật:

Mister Gold

Tên dự án:

Quy trình hướng dẫn về điện

Thời lượng dự án:

Thời gian tiêu chuẩn (3 tháng)

Mô tả dự án

TÓM TẮT DỰ ÁN

Electron là một trong những công cụ phổ biến nhất để xây dựng ứng dụng dành cho máy tính đa nền tảng bằng JavaScript, HTML và CSS. Một bộ sưu tập ứng dụng được xây dựng trên Electron có gần 900 mục và danh sách này liên tục phát triển. Một số công cụ phổ biến nhất dành cho nhà phát triển như Visual Studio Code, Atom, Postman, Slack, GitKraken được xây dựng trên Electron.

Electron trở nên phổ biến nhờ độ dốc học tập đơn giản và ngưỡng tham gia thấp – tất cả những ai biết JavaScript, HTML, ngăn xếp CSS đều có thể tạo ứng dụng của riêng mình. Tỷ lệ tăng trưởng tổng thể rất lớn cho thấy nhu cầu tạo video hướng dẫn và hướng dẫn bắt đầu dễ dàng nắm bắt và sử dụng.

Mục tiêu của dự án là giúp những nhà xây dựng ứng dụng mới làm quen với khung Electron có thêm sự tự tin và mang đến cho họ trải nghiệm nhất quán và đơn giản trong việc phát triển các ứng dụng Electron của riêng họ từ đầu.

Vấn đề về dự án

Sau đây là danh sách các vấn đề quan trọng nhất liên quan đến tài liệu hướng dẫn về Electron: 1. Điểm xuất phát không rõ ràng và thông tin giới thiệu không trực quan về các bước phát triển ứng dụng 2. Thông tin rời rạc và thừa liên quan đến quy trình phát triển ứng dụng 3. Các phần hướng dẫn "bắt đầu" không được sắp xếp hợp lý và không có nguồn đáng tin cậy

ĐỀ XUẤT DỰ ÁN

Theo mục tiêu của dự án và các vấn đề nêu trên, sau đây là danh sách các điểm cải tiến được đề xuất: 1. Cập nhật các hướng dẫn hiện có. Để các bước đầu tiên diễn ra suôn sẻ và nhất quán, bạn nên cập nhật các tài liệu sau đây theo hướng chuyển đổi dần từ đơn giản đến phức tạp hơn: - Môi trường dành cho nhà phát triển - Viết ứng dụng Electron đầu tiên của bạn - Thêm tính năng vào ứng dụng (tạo trang tóm tắt) - Đóng gói và phân phối ứng dụng 2. Điều chỉnh cấu trúc thư mục tài liệu. Để cho nhà phát triển mới biết những điều cần thiết để bắt đầu và những bước có thể được xem là bước tiếp theo, trang tài liệu phải có cả phần hình ảnh và phần phân chia theo ngữ cảnh của các bước để đưa ứng dụng đầu tiên lên hoạt động nhanh nhất có thể. Việc tái cấu trúc cũng bao gồm hướng dẫn về các bước tiếp theo có thể có. 3. Sắp xếp và hợp nhất tài liệu phát triển ứng dụng. Tất cả các tính năng phải có một bộ hướng dẫn thống nhất về cách cài đặt/bật tính năng này, cách bắt đầu nhanh, cách làm việc với ứng dụng sau lần khởi chạy đầu tiên và cách phân phối ứng dụng đó. 4. Bao gồm kho lưu trữ electron-api-demos trong tài liệu. Kho lưu trữ electron-api-demos chứa một tập hợp các ví dụ cho biết cách thêm các tính năng vào ứng dụng Electron của bạn. Bạn nên đưa thông tin này vào hướng dẫn Thêm tính năng vào ứng dụng để nhất quán với chiến lược nội dung dựa trên một nguồn đáng tin cậy. 5. Tích hợp các ví dụ về Electron Fiddle vào tài liệu. Bước này sẽ giúp các nhà phát triển mới dễ dàng xem cách một đoạn mã cụ thể hoạt động mà không cần lặp lại các bước theo cách thủ công. Việc tích hợp bao gồm viết mã mẫu cho các hướng dẫn cập nhật và thêm nút "Launch in Fiddle" (Khởi chạy trong Fiddle) vào các khối mã.

Diễn biến chính

Giai đoạn xem xét đơn đăng ký – Làm quen với cộng đồng và những người mà bạn muốn hợp tác. Tìm hiểu hướng dẫn và các phương pháp hay nhất về việc đóng góp cho cộng đồng. Thực hiện các đóng góp đầu tiên. Kết nối cộng đồng – Khám phá cộng đồng. Kiểm tra trạng thái hiện tại của tài liệu Electron. Xác định điểm yếu. Tuần 1 – Điều chỉnh với các cố vấn về các mốc và sản phẩm của dự án Tuần 2 – Xem lại trang Môi trường dành cho nhà phát triển và Viết ứng dụng Electron đầu tiên của bạn Tuần 3 – Xem lại Cấu trúc ứng dụng, Thêm tính năng vào ứng dụng, Đóng gói ứng dụng và trang phân phối. Tạo một trang tóm tắt có danh sách các tính năng có thể thêm vào ứng dụng Tuần 4 – Định cấu trúc lại thư mục tài liệu Tuần 5 – Chuẩn bị mẫu về cách tích hợp electron-api-demos vào tài liệu chính Tuần 6 – 7 – Di chuyển kho lưu trữ electron-api-demos Tuần 8 – Chuẩn bị mẫu về cách tích hợp Electron Fiddle vào tài liệu chính. Viết mẫu đầu tiên. Tuần 9 – 10 – Tích hợp Electron Fiddle vào tài liệu chính Tuần 11 – Hoàn thiện cấu trúc và các trang tài liệu chính sau khi di chuyển kho lưu trữ electron-api-demos và các mẫu Electron Fiddle Tuần 12 – Đánh giá kết quả

PHÂN TÍCH CHI TIẾT VỀ CỘT MỐC

KHOẢNG THỜI GIAN XEM XÉT ỨNG DỤNG Phần đầu tiên của giai đoạn này sẽ là kiểm tra các kênh cộng đồng và mã nguồn, đồng thời liên hệ với những người tận tâm với dự án.

Phần thứ hai của khoảng thời gian này sẽ dành để kiểm tra văn hoá đóng góp nói chung, xem xét hướng dẫn đóng góp và các phương pháp hay nhất. Đây sẽ là thời điểm để bạn đóng góp lần đầu tiên để xem quy trình hoạt động như thế nào.

GẮN KẾT CỘNG ĐỒNG

Lần này, chúng ta sẽ dành thời gian để kiểm tra kỹ hơn thư mục tài liệu cùng với lộ trình của thư mục này. Dựa trên thông tin đó, bạn có thể xác định những điểm yếu (ví dụ: thiếu hoặc không đầy đủ các phần) cần cải thiện. Tạo yêu cầu kéo (nếu có thể) để lấp đầy khoảng trống.

TUẦN 1 – TUẦN 2

Tuần đầu tiên sẽ dành để trao đổi với người cố vấn nhằm điều chỉnh các mốc dự kiến và đảm bảo việc hoàn thành đúng hạn.

Tuần thứ hai là về việc sửa đổi Môi trường dành cho nhà phát triển và Viết các trang Ứng dụng điện tử đầu tiên của bạn. Đối với trang Môi trường dành cho nhà phát triển, bạn sẽ phải viết lại phần tổng quan chung và chỉnh sửa. Đối với trang Viết ứng dụng Electron đầu tiên, bạn sẽ phải tạo một hướng dẫn từng bước nhất quán với điểm bắt đầu và điểm kết thúc rõ ràng, xoá thông tin thừa (chẳng hạn như hai khối mã tương tự nhau trong phần Electron Development in a Nutshell (Phát triển Electron tóm tắt) và Trying this example (Thử ví dụ này)).

Nội dung cung cấp: Hướng dẫn giới thiệu đã được sửa đổi, dễ làm theo về cách bắt đầu nhanh với ứng dụng electron.

TUẦN 3

Tuần này sẽ dành riêng cho: 1. các điểm cải tiến của trang Cấu trúc ứng dụng. Điều này bao gồm: - viết lại thông tin hiện có trong phần Quy trình chính và Quy trình kết xuất để đơn giản và trực quan hơn cho người đọc lần đầu - thêm nội dung trình bày trực quan về cấu trúc, cách kết nối các quy trình, cách chúng giao tiếp và sự khác biệt cốt lõi của các quy trình đó. Ví dụ về hình ảnh: Một, Hai, Ba (chất lượng thấp). 2. hợp nhất thông tin về tất cả các tính năng mà bạn có thể thêm vào ứng dụng Electron của mình. Việc này bao gồm việc viết lại hướng dẫn để có một bộ hướng dẫn thống nhất về cách cài đặt/bật một tính năng cùng với ví dụ về cách hoạt động của tính năng đó. Ngoài ra, một trang mới (tóm tắt) sẽ được tạo để liệt kê tất cả các tính năng có thể sử dụng. Hướng dẫn hợp nhất có thể có dạng như sau: - Tổng quan - Ví dụ: - Mã mẫu - Ví dụ trực quan (nếu có thể)

1. đơn giản hoá trang Phân phối ứng dụng. Bao gồm: a. hợp nhất tính năng Đóng gói ứng dụng vào hướng dẫn Phân phối ứng dụng b. chia các phương thức phân phối thành tự động và thủ công c. lấy electron-forge làm ví dụ về phương thức phân phối tự động d. lấy thông tin về asar từ trang Đóng gói ứng dụng và mô tả việc sao chép tệp nguồn và tạo bản lưu trữ asar làm ví dụ về phương thức phân phối thủ công. #### TUẦN 4 Tuần này sẽ dành riêng cho việc tái cấu trúc thư mục tài liệu. Thư mục này bao gồm:

1 – chia các hướng dẫn hiện có thành ít nhất 3 danh mục: a. Bắt đầu nhanh b. Tìm hiểu kiến thức cơ bản c. Các bước nâng cao

Danh mục Bắt đầu nhanh sẽ chứa các hướng dẫn cơ bản (cài đặt, định cấu hình, phân phối) để tạo một loạt hướng dẫn nhất quán giúp người mới bắt đầu nhanh từ đầu. Mỗi hướng dẫn phải chứa đường liên kết đến hướng dẫn trước/sau trong loạt bài viết.

Cấu trúc có thể như sau: 1. Điều kiện tiên quyết 2. Cài đặt Electron 3. Tạo một ứng dụng cơ bản 4. Đóng gói/Phân phối ứng dụng

Sau khi hoàn tất phần Bắt đầu nhanh, người dùng sẽ nắm được kiến thức cơ bản về cách hoạt động của ứng dụng Electron và sẽ có một ứng dụng Electron có thể phân phối hoạt động hoàn toàn.

Danh mục "Tìm hiểu các khái niệm cơ bản" sẽ có các hướng dẫn nhằm củng cố kiến thức về Electron và mở rộng ứng dụng đã tạo trong các phần Bắt đầu nhanh. Các hướng dẫn này bao gồm: - Cấu trúc ứng dụng - Thêm tính năng vào ứng dụng của bạn - Mẫu và CLI

Danh mục Các bước nâng cao sẽ chứa các hướng dẫn nâng cao hơn nhằm định cấu hình và tinh chỉnh ứng dụng Electron: - Kiểm thử và gỡ lỗi - Hỗ trợ tiếp cận - Bảo mật - Bản cập nhật

2 – giảm số lượng trang tài liệu. Phiên bản hiện tại của tài liệu có một số nội dung trùng lặp và hướng dẫn chưa được phân loại. Ví dụ: – Cài đặt và cài đặt điện tử trong phần Viết ứng dụng đầu tiên – Đóng gói và đóng gói ứng dụng vào một tệp trong Phân phối ứng dụng – Hướng dẫn chưa được phân loại trong danh mục Chi tiết và Nâng cao: Đề xuất: di chuyển các tài liệu sau sang GitHub và loại trừ khỏi tài liệu chính. Các tài liệu này dành riêng cho nguyên tắc phát triển Electron và kho lưu trữ nguồn là nơi đầu tiên để tìm kiếm các tài liệu đó: - Phát triển Electron - Phát triển Chromium - Phát triển V8 - Các vấn đề trong Electron - Bản vá trong Electron - Yêu cầu kéo - Cấu trúc thư mục mã nguồn - Kiểm thử - Kiểu lập trình

Ý tưởng chính của việc giảm số lượng tài liệu là loại bỏ một số lượng lớn hướng dẫn hiện có, kết hợp các mảnh thông tin rời rạc với nhau và cung cấp cho người mới một phiên bản tài liệu Electron có cấu trúc rõ ràng, dễ điều hướng và thân thiện với người dùng hơn.

TUẦN 5 – 7

Tuần 5 sẽ dành riêng cho việc chuẩn bị một mẫu (cách) tích hợp electron-api-demos vào tài liệu chính. Mẫu này có thể có dạng như sau: 1. Trong tài liệu chính, bên dưới mục “Thêm tính năng vào ứng dụng”, hãy tạo các danh mục được biểu thị trong electron-api-demos 2. Bằng cách xem qua từng danh mục, hãy chuyển các ví dụ minh hoạ sang tài liệu chính: - Bạn có thể lấy mã mẫu từ mã nguồn hoặc từ nội dung mô tả tính năng tương ứng trong ứng dụng - Mỗi ví dụ được chuyển phải theo sau là nội dung mô tả liên quan - Mỗi ví dụ con (ví dụ: hộp thoại Lỗi là một ví dụ con của hộp thoại Sử dụng hộp thoại hệ thống) phải được chuyển vào bên dưới ví dụ mẹ

LƯU Ý 1: có một số ví dụ có trong cả electron-api-demo và tài liệu chính (ví dụ: phím tắt, kéo và thả). Trong trường hợp này, ví dụ từ electron-api-demos sẽ được ưu tiên và ví dụ trong tài liệu chính sẽ bị bỏ qua.

LƯU Ý #2: Nhiều ví dụ trong ứng dụng electron-api-demos có bản xem trước Bản minh hoạ trực tiếp về tính năng hoặc chức năng được mô tả. Chức năng này sẽ bị bỏ qua cho đến khi tích hợp Electron Fiddle vào các tuần từ 9 đến 10.

1. Cập nhật trang liệt kê tất cả tính năng hiện có để sử dụng (được tạo trong Tuần 3) theo hệ thống phân cấp ví dụ mới.

Tuần 6 và 7 sẽ được dành riêng để chuyển các ví dụ electron-api-demos sang tài liệu chính theo mẫu được mô tả ở trên. Ở bước cuối cùng, bạn nên xoá hoặc ngừng sử dụng kho lưu trữ electron-api-demos.

TUẦN 8 – 10

Tuần 8 sẽ dành riêng cho việc chuẩn bị một mẫu (cách) tích hợp Electron Fiddle vào tài liệu chính. Ý tưởng này đã được nhóm Electron cùng với các tình nguyện viên trong cộng đồng triển khai (xem thông tin chi tiết trong vấn đề #20442), nhưng cần phải hoàn thiện một cách chính xác.

Để tiếp tục với các mẫu Fiddle, mẫu cơ bản có thể có dạng như sau: 1. Chọn một ví dụ trong tài liệu chính (ví dụ: bắt đầu nhanh). Tại thời điểm này, tài liệu cũng phải chứa các ví dụ về electron-api-demos; 2. Tạo lại ví dụ trong Electron Fiddle (sử dụng mã ví dụ hoặc mã nguồn làm điểm xuất phát); 3. Lưu Fiddle cục bộ vào một thư mục; 4. Di chuyển ví dụ vào /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * Danh sách ví dụ đã hoàn tất được mô tả trong phần "Danh sách bản minh hoạ" của vấn đề. 5. Thêm nút "Launch in Fiddle" (Chạy trong Fiddle) như mô tả trong nhận xét ban đầu của vấn đề #2848.

Tuần 9 và 10 sẽ dành riêng cho việc tích hợp các ví dụ electron-api-demos (đã được chuyển đổi thành Fiddles) vào tài liệu chính theo mẫu được mô tả ở trên.

TUẦN 11

Tuần này, chúng ta sẽ hoàn tất dự án viết sau khi di chuyển thành công kho lưu trữ electron-api-demos và các mẫu Electron Fiddle. Bao gồm: - kiểm tra để đảm bảo tất cả các ví dụ về mã hiện có đều có nút "Launch in Fiddle" (Chạy trong Fiddle) - kiểm tra để đảm bảo tất cả các ví dụ về mã hiện có đều hoạt động đúng cách dưới dạng Fiddles - kiểm tra để đảm bảo tài liệu chính không còn tham chiếu đến kho lưu trữ electron-api-demos

TUẦN 12

Hoàn tất công việc đã hoàn thành. Kiểm tra chấp nhận.