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ở:
- WordPress
- Tác giả kỹ thuật:
- tacitonic
- Tên dự án:
- Bộ hướng dẫn đầy đủ và mới về văn phong viết tài liệu
- Thời lượng dự án:
- Chạy trong thời gian dài (5 tháng)
Mô tả dự án
Bản tóm tắt:
WordPress là một tổ chức phần mềm phi lợi nhuận toàn cầu, chuyên cung cấp cho các cộng đồng trên toàn cầu những phần mềm chú trọng vào khả năng hỗ trợ tiếp cận, hiệu suất, bảo mật và dễ sử dụng. Mục tiêu của WordPress là dân chủ hoá việc xuất bản và phần mềm nguồn mở trên web. Trong thời đại kỹ thuật số, trang web thực sự là mặt tiền trực tuyến của một tổ chức/cá nhân; và WordPress thực hiện một nhiệm vụ to lớn là phục vụ hiệu quả hàng trăm triệu người dùng – chiếm 35% Internet mà WordPress chạy – bằng phần mềm của họ. Để phục vụ hiệu quả hơn cho những người dùng này, tài liệu là yếu tố thiết yếu và được hầu hết các nhà phát triển, quản trị viên và người dùng cuối sử dụng. Do đó, tài liệu có thể được coi là một yếu tố chính của hệ sinh thái WordPress. Tài liệu hiện tại của WordPress không bao gồm một bộ quy tắc và nguyên tắc về kiểu dáng chung và thống nhất để xuất bản. Mục đích của đề xuất này là tạo một bộ nguyên tắc đầy đủ và mới mẻ về phong cách tài liệu, áp dụng chung cho tài liệu WordPress. Ý tưởng dự án liên quan đến việc hợp nhất tất cả các khía cạnh của nguyên tắc thiết kế và phong cách như ngữ nghĩa, cú pháp, nguyên tắc ngữ pháp, dấu câu, quy tắc dành riêng cho hoạt động phát triển, thuộc tính thiết kế và thông tin cụ thể về định dạng. Ngôn ngữ này cũng kết hợp các quy ước ngôn ngữ như giọng, âm điệu, thì, tất cả các phần của lời nói, cũng như quy ước đặt tên. Các công cụ, ngôn ngữ và nền tảng được sử dụng sẽ là WordPress CMS, GitHub, Markdown và cũng có thể bao gồm PHP/MySQL, HTML/CSS và JavaScript.
Kế hoạch dự án:
Trạng thái hiện tại của hướng dẫn về tài liệu trên WordPress: Nhóm Tài liệu WordPress đã và đang triển khai một phương pháp liên quan đến các nguyên tắc xuất bản chưa được khai báo nhưng nhất quán. Tuy nhiên, đôi khi, một số phần tử được giả định trước và quá trình này trở nên suy đoán. Không có tiêu chuẩn và tiêu chí cố định nào để viết và xuất bản bài viết cho WordPress. Nhóm tài liệu đã viết các nguyên tắc về kiểu dành riêng cho dự án, nhưng không có nguyên tắc nào áp dụng được cho mọi dự án. Hầu hết các nguyên tắc về kiểu hiện có không được hợp nhất trong một cuốn sách hướng dẫn hoặc không còn được dùng nữa và cần được cập nhật. Do đó, cần thiết kế và phát triển một hướng dẫn kiểu thống nhất để chuẩn hoá tài liệu WordPress.
Mục tiêu:
Hơn 35% trang web trên Internet chạy trên WordPress, điều này cho thấy hàng triệu nhà phát triển và người dùng cuối đang sử dụng các chức năng ấn tượng của WordPress. Tài liệu là một phần thiết yếu để hỗ trợ các nhà phát triển và người dùng này thực hiện hiệu quả các chức năng này mà không gặp bất kỳ rắc rối nào, ngay cả trong trường hợp bất tiện. Mục tiêu tổng thể của đề xuất dự án này là chuẩn hoá hướng dẫn thiết kế và kiểu, hợp nhất các hướng dẫn kiểu hiện có và cập nhật cũng như bổ sung các quy định và thông số kỹ thuật mới cho tài liệu WordPress. Điều này sẽ giúp tài liệu WordPress dễ sử dụng, đơn giản và thống nhất.
Cách triển khai:
Theo đề xuất của người cố vấn (Jon Ang) cho dự án này, bạn có thể tiếp cận dự án theo 4 giai đoạn: Khám phá, Xác định, Triển khai và Bảo trì. Trước khi bắt đầu dự án, trong giai đoạn trước khi thực tập, tôi sẽ làm việc với người cố vấn và hoàn tất lịch trình và tiến trình phù hợp theo tiến trình và sản phẩm tiếp theo của tôi. Tôi sẽ làm quen thêm với hệ thống WordPress và các quy trình làm việc cho dự án này.
Khi chương trình thực tập bắt đầu, tôi sẽ thảo luận và soạn bản tóm tắt của kế hoạch với người cố vấn. Các yêu cầu và điều cần thiết sẽ được xác định. Trước tiên, tôi sẽ trình bày sơ lược về quy trình tài liệu và quy trình tương tác của người dùng. Sau đó, các khung bố cục của từng phần, danh mục và thành phần sẽ được vẽ đường viền. Sau đó, cố vấn của tôi sẽ xem xét các bố cục này. Nếu cần, bố cục sẽ được thiết kế lại và thêm/xoá một số thành phần. Sau đó, tôi sẽ tiến hành nghiên cứu người dùng để xác định khả năng hữu dụng và khả thi của luồng giao diện. Sau đó, Hướng dẫn về phong cách tài liệu sẽ được triển khai (như minh hoạ trong sơ đồ bên dưới) theo từng phần. Bạn cũng có thể tham khảo hướng dẫn về quy tắc sử dụng của các tổ chức khác theo giấy phép nguồn mở hoặc Creative Commons để bổ sung cho hướng dẫn của chúng tôi. Nếu trong khoảng thời gian này, có bất kỳ khó khăn nào về khả năng hữu dụng, tôi sẽ thiết kế lại các thành phần đó.
Quá trình kiểm thử và tối ưu hoá sẽ được thực hiện sau khi hoàn tất hướng dẫn về kiểu và tích hợp với HelpHub. Mọi lỗ hổng bảo mật, phần tử hoặc thành phần dư thừa sẽ được khắc phục. Hoạt động kiểm thử giao diện người dùng và mã sẽ được thực hiện, đồng thời các lỗi và lỗi không mong muốn sẽ được khắc phục (nếu cần). Chúng tôi sẽ tiến hành kiểm tra chất lượng cuối cùng cho toàn bộ hướng dẫn quy tắc về ngôn ngữ, ngữ pháp, chính tả, dấu câu, v.v.
Những việc cần làm đang chờ xử lý do bị chậm trễ ngoài dự kiến sẽ được hoàn tất trong khoảng thời gian chờ. Bạn có thể triển khai các chức năng hoặc tính năng bổ sung được xác định là khả thi trong suốt quá trình thực hiện dự án sau khi quá trình kiểm thử cuối cùng hoàn tất. Hệ thống sẽ tạo một kế hoạch triển khai và gửi sản phẩm hoàn chỉnh.
Công cụ và phương pháp:
Tài liệu sẽ được biên dịch và chỉnh sửa trên một nền tảng cộng tác, chẳng hạn như Google Tài liệu. Nếu cần xuất bản qua GitHub, bạn cũng có thể triển khai các ngôn ngữ đánh dấu như Markdown hoặc GitHub Flavored Markdown. Đối với các tiêu chuẩn thiết kế và kiểu, bạn cũng có thể tham khảo nguyên tắc kiểu nguồn mở. Cuối cùng, tài liệu hoàn chỉnh sẽ được định dạng và xuất bản bằng WordPress.
Bảng thành phần:
Đây là danh sách đầy đủ các thành phần có thể được triển khai trong Hướng dẫn về kiểu. Nguyên tắc về tài liệu – Hỗ trợ tiếp cận, Cấu trúc tài liệu, Mã hoá, Nguồn bên ngoài, Sự thật, Phông chữ, Đối tượng trên toàn cầu, Tính bao gồm, Tính hợp pháp, Hỗ trợ tiếp cận trên nhiều nền tảng, Không gây hiểu lầm, Không đưa ra tuyên bố quá mức, Bố cục trang, Tính chính xác về chính trị, Giao thức, Bảo mật, Cấu trúc câu, Văn phong súc tích, Biện pháp và phong cách, Không thiên vị
Ngôn ngữ và ngữ pháp – Từ viết tắt và chữ viết tắt, Câu khẳng định và câu phủ định, Tính từ, Viết hoa, Mệnh đề, Câu trực tiếp/gián tiếp, Ngôi thứ nhất/thứ hai/thứ ba, Giới tính, Bảng thuật ngữ, Danh từ, Tiếp đầu ngữ và hậu tố, Giới từ, Đại từ, Tham chiếu, Tục ngữ và tiếng lóng, Cách viết, Thuật ngữ kỹ thuật, Thì, Động từ, Giọng
Dấu câu – Dấu nháy đơn và dấu ngoặc kép, dấu hai chấm và dấu chấm phẩy, dấu phẩy, dấu ba chấm, dấu chấm than, dấu gạch nối và dấu gạch ngang, dấu ngoặc đơn, dấu chấm, dấu chấm hỏi, dấu gạch chéo
Định dạng – Tóm tắt, Giới thiệu, Lời tựa, Tên thương hiệu, Tên sản phẩm, Chú thích, Đoạn mã, Khối mã, Ngày và giờ, Múi giờ, Địa điểm, Đơn vị tiền tệ, Tên tệp, Chú thích cuối trang, Tiêu đề và tiêu đề phụ, Làm nổi bật (In đậm, In nghiêng, Gạch chân, Gạch ngang, Dấu ngoặc kép), Dấu thụt lề, Chỉ mục, Đường liên kết và URL, Danh sách, Dấu đầu dòng, Số thứ tự, Nội dung nghe nhìn (Hình ảnh, Video) và Hình minh hoạ, Ghi chú, Cảnh báo, Mẹo, Số và Số điện thoại, Đa ngôn ngữ, Bản dịch, Ký tự ngôn ngữ, Khoảng cách, Bảng, Văn bản, Nhãn hiệu, Bản quyền, Bằng sáng chế, Tài liệu tham khảo, Hướng dẫn và quy trình, Thành phần giao diện người dùng, Đơn vị đo lường
Giao diện người dùng – Hoạt động, Nút, Đoạn mã, Khối mã, Giao diện dòng lệnh, Hộp thoại, Trình đơn và trình đơn thả xuống, Cửa sổ bật lên và cảnh báo, Thẻ, Thuật ngữ, Thành phần giao diện người dùng, Cửa sổ
Mã – CSS, HTML, JS, Markdown, MySQL, PHP, Cú pháp, XML
Từ điển/bảng chú giải thuật ngữ sử dụng từ – A đến Z