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ở:
- ESLint
- Tác giả kỹ thuật:
- Khawar
- Tên dự án:
- Sắp xếp lại/viết lại tài liệu về cấu hình
- Thời lượng dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Bản tóm tắt
Mục tiêu của dự án này là tái cấu trúc tài liệu cấu hình cho ESLint và tạo một cấu trúc thông tin hiệu quả. Việc này sẽ giúp điều hướng dễ dàng hơn, đồng thời cải thiện khả năng hữu dụng và mức độ hữu ích của tài liệu.
Tóm tắt dự án Tài liệu về cấu hình của ESLint (https://eslint.org/docs/user-guide/configure), ở trạng thái hiện tại, cung cấp nhiều thông tin về một trang. Mặc dù có tiêu đề, tiêu đề phụ và đoạn văn thích hợp trên trang, tài liệu có thể khiến bạn cảm thấy choáng ngợp. Không có cách nào để chuyển đến một phần cụ thể trên trang, điều này gây khó chịu cho người dùng quan tâm đến một phần cụ thể. Do sự thiếu tổ chức này, thông tin cũng có thể bị mất, không đáp ứng được mục đích của nó và yêu cầu người dùng nỗ lực thêm.
Tuy nhiên, bạn có thể giải quyết những vấn đề này bằng một số bước cẩn thận. Tôi đề xuất một quy trình kiểm tra nội dung làm bước đầu tiên trong quá trình tái cơ cấu này. Hoạt động kiểm tra nội dung không chỉ giúp xác định các vấn đề trong quá trình trình bày thông tin, mà còn nêu bật những thiếu sót của nội dung đó (ví dụ: thông tin lỗi thời hoặc không đầy đủ). Sau đó, tôi dự định tạo Cấu trúc thông tin (IA) để công bố mạng kiến thức. Nhờ đó, chúng tôi có thể nhóm thông tin theo các chủ đề khác nhau và tìm ra mối liên hệ giữa nhiều chủ đề có liên quan chặt chẽ. Sau đó, thông tin chi tiết thu được thông qua hai phương pháp này sẽ được dùng để chia tài liệu một trang thành nhiều trang. Sau đó, bạn có thể liên kết và tham chiếu chéo toàn bộ gói trong Markdown. Do đó, sẽ có phiên bản tài liệu cấu hình được tổ chức tốt hơn, dễ điều hướng và dễ hiểu hơn.
Động lực Mặc dù tôi đã sử dụng phần mềm nguồn mở được một thời gian, nhưng tôi mới quen với thuật ngữ này, tương tự như kiến thức của tôi về phần mềm Tìm lỗi mã nguồn. Khi bắt đầu học Python (thông qua edX), tôi đã tự hỏi làm thế nào mà những lỗi nhỏ có thể làm hỏng toàn bộ mã. Tôi nghĩ rằng bạn nên kiểm thử mã của mình bằng cách nào đó và xác định lỗi, sau đó tôi mới biết đến thuật ngữ "tìm lỗi mã nguồn". Tôi chưa sử dụng đúng cách phần mềm tìm lỗi mã nguồn nhưng tôi chắc chắn rằng những phần mềm này sẽ giúp cuộc sống của tôi dễ dàng hơn rất nhiều trong những ngày tới.
Với nền tảng là Kỹ sư điện và một số kinh nghiệm lập trình, tôi có thể hiểu rõ hơn về các vấn đề lập trình và yêu cầu của lập trình viên. Ngoài ra, bằng sau đại học về Kỹ thuật và Truyền thông chuyên nghiệp giúp tôi hỗ trợ người dùng, cố gắng giúp cuộc sống của mọi người trở nên dễ dàng hơn. Kỹ năng và chuyên môn của tôi sẽ là một sự kết hợp hiệu quả cho dự án này, giúp nâng cao giá trị cho tài liệu của ESLint.
Mục tiêu Mục tiêu tổng thể của dự án này là đảm bảo rằng tài liệu trên trang cấu hình của ESLint dễ hiểu và không gây choáng ngợp người dùng. Để dự án thành công, điều quan trọng là việc điều hướng nội dung phải dễ dàng và không có bất kỳ rắc rối nào. Sau đây là các mục tiêu quan trọng của dự án. – Tiến hành kiểm tra nội dung toàn diện – Tạo Cấu trúc thông tin để hiểu luồng thông tin – Cải thiện Cấu trúc thông tin để sắp xếp lại tài liệu – Xác định các đường liên kết và tham chiếu giữa các phần nội dung khác nhau – Viết lại/Chỉnh sửa một số phần của tài liệu, nếu cần để đáp ứng các yêu cầu về cấu hình lại
– Đảm bảo nội dung linh hoạt và có thể sử dụng lại
Mô tả dự án Cấu hình của ESLint là một tính năng quan trọng, giúp ESLint có thể tuỳ chỉnh. Người dùng quan tâm đến cấu hình chắc chắn sẽ quan tâm đến một hoặc hai khía cạnh tại một thời điểm nhất định. Do đó, điều quan trọng là người dùng được hướng dẫn đến chủ đề cụ thể mà họ quan tâm, từ đó cung cấp cho họ giải pháp một cách hiệu quả. Trạng thái hiện tại của tài liệu về cấu hình cho ESLint chứa rất nhiều thông tin hữu ích nhưng được sắp xếp theo cách có thể khiến người dùng cảm thấy bị choáng ngợp, khó chịu và lạc lõng. Ví dụ: nếu muốn tìm hiểu về cách sử dụng trình bổ trợ của bên thứ ba trong ESLint, người dùng sẽ phải cuộn xuống để xem phần thảo luận về cách chỉ định trình phân tích cú pháp, môi trường và toàn cục. Toàn bộ quá trình thực hành này khiến người dùng mệt mỏi và có thể khiến họ rời khỏi trang web. Tương tự, nếu người dùng đang ở giữa trang và muốn chuyển đến một phần cụ thể hoặc chỉ muốn xem các chủ đề tương tự, thì đó sẽ không phải là một nhiệm vụ dễ dàng đối với họ, vì không có sự trợ giúp nào như vậy được cung cấp cho người dùng. Bạn cần chú ý ngay đến những vấn đề này vì chất lượng của mọi tài liệu, bất kể được soạn thảo tốt đến đâu, đều phụ thuộc vào mức độ hữu ích của tài liệu đó. Tôi đề xuất các giải pháp cho những vấn đề này và các vấn đề liên quan khác trong phần thảo luận sau.
Kiểm tra nội dung Bước đầu tiên trong quá trình sắp xếp lại tài liệu cấu hình là tiến hành kiểm tra nội dung toàn diện. Việc kiểm tra sẽ nhằm mục đích xác định một số vấn đề chính như nội dung lỗi thời, trùng lặp, thiếu nội dung, v.v. Sau đó, một bảng tính kiểm tra nội dung được tạo sẽ được chia sẻ với nhóm quản lý và tài liệu để lấy ý kiến phản hồi của họ. Việc này sẽ giúp chúng tôi đề ra chiến lược mới để xây dựng cấu trúc và trình bày tài liệu.
Tạo cấu trúc thông tin Để hiểu được mạng kiến thức hoặc luồng thông tin trong tài liệu cấu hình, việc tạo cấu trúc thông tin (IA) có thể rất hữu ích. Kết quả của quy trình kiểm tra nội dung sẽ là nền tảng tốt để hiểu rõ và phát triển luồng thông tin. Sau đó, một phiên bản cải tiến của IA sẽ được tạo để sắp xếp và trình bày tài liệu theo cách hiệu quả hơn. AI cải tiến này không chỉ tái cấu trúc nội dung hiện tại mà còn xác định các đường liên kết và nhánh giữa nhiều phần của tài liệu, từ đó tạo ra một mạng lưới hiệu quả. Ví dụ: nội dung về "Định cấu hình quy tắc" có thể được theo sau bằng một đường liên kết dẫn đến "Tắt quy tắc bằng nhận xét cùng dòng". Bạn cũng có thể xác định các đường liên kết khác như vậy, từ đó tạo mối quan hệ giữa các phần khác nhau của tài liệu.
Kiểm tra nội dung và IA sẽ cung cấp đầy đủ thông tin để tạo mục lục chi tiết kèm theo các đường liên kết dẫn đến các phần và tiểu mục cụ thể trong tài liệu. Việc tạo các tệp riêng cho từng phần và thêm các tệp tham chiếu thích hợp vào các phần khác có thể làm tăng giá trị cho toàn bộ bộ tài liệu. Bạn có thể tạo mục lục cho người dùng truy cập vào tài liệu cấu hình, nhờ đó hỗ trợ hành trình của họ khi họ truy cập vào trang web. Bảng mục lục có thể bao gồm tất cả tiêu đề cấp 1 và cấp 2 để đảm bảo ngắn gọn nhưng đầy đủ. Ví dụ: một phương pháp như vậy là phương pháp mà Prettier (https://prettier.io/docs/en/index.html) sử dụng để sắp xếp tài liệu.
Tất cả tài liệu sẽ được tạo bằng Markdown để đơn giản hoá và sắp xếp mọi thứ một cách hợp lý. Chúng tôi sẽ đặc biệt chú ý để đảm bảo tài liệu có thể sử dụng lại vì tài liệu có thể phát triển và thay đổi trong tương lai.
Các công cụ cần sử dụng Một số công cụ quan trọng có thể hữu ích khi thực hiện dự án – Draw.io để tạo hình minh hoạ cho IA nếu cần – Atom (hoặc một trình chỉnh sửa tương tự) để viết và chỉnh sửa tài liệu trong Markdown
– GitHub để đảm bảo việc kiểm soát phiên bản của tài liệu
Các mốc quan trọng Từ khi gửi đề xuất đến khi hoàn thành dự án, các mốc quan trọng dự kiến sau đây sẽ đảm bảo dự án được hoàn thành đúng tiến độ, duy trì đúng quy trình trong quá trình thực hiện.
Từ ngày 10 tháng 7 đến ngày 16 tháng 8 năm 2020: Xem xét và lựa chọn đề xuất Tôi sẽ xem tài liệu về ESLint và phát triển các kỹ năng cần thiết để hoàn thành dự án (chẳng hạn như viết Markdown, cộng tác trên GitHub). Tôi cũng sẽ đóng góp cho tài liệu này thông qua GitHub và tương tác với những người khác để hiểu rõ hơn về tài liệu.
Ngày 17 tháng 8 năm 2020 – Ngày 13 tháng 9 năm 2020: Kết nối với cộng đồng Trong thời gian kết nối với cộng đồng, tôi sẽ tinh chỉnh đề xuất của mình theo các cuộc thảo luận với các cố vấn và nhóm liên quan. Tôi cũng sẽ chỉnh sửa các mục tiêu và mốc quan trọng nếu cần. Ngoài ra, tôi sẽ đảm bảo đưa vào danh sách rút gọn các công cụ sẽ được dùng để làm việc trên dự án.
Ngày 14 tháng 9 năm 2020 – Ngày 19 tháng 9 năm 2020: Kiểm tra nội dung Để bắt đầu dự án, tôi sẽ tiến hành kiểm tra nội dung toàn diện của tài liệu cấu hình. Mục tiêu là làm nổi bật các vấn đề về nội dung và cách trình bày.
Ngày 20 tháng 9 năm 2020 – Ngày 25 tháng 9 năm 2020: Cấu trúc thông tin (IA) Sau khi kiểm tra nội dung, tôi sẽ tạo IA của tài liệu cấu hình. Tôi sẽ tập trung trình bày mạng tri thức theo cách dễ hiểu. Sau đó, điều này sẽ giúp cải thiện luồng thông tin.
Ngày 26 tháng 9 năm 2020 – ngày 30 tháng 9 năm 2020: Đường liên kết và tài liệu tham khảo Tôi sẽ phân tích IA trong giai đoạn này để lập bản đồ các đường liên kết và tài liệu tham khảo giữa các phần khác nhau của tài liệu. Tôi cũng sẽ tạo một hệ phân cấp cho tất cả các phần, nhờ đó cải thiện IA trong quá trình này.
Ngày 1 tháng 10 năm 2020 – Ngày 3 tháng 10 năm 2020: Bản đồ cuối cùng Nhờ thông tin chi tiết thu được thông qua quy trình kiểm tra nội dung và IA, tôi sẽ tạo một bản đồ cuối cùng để triển khai trong tài liệu cấu hình được sắp xếp lại. Bản đồ toàn diện này sẽ chứa mục lục, hệ thống phân cấp chủ đề và danh sách đường liên kết cũng như nội dung tham chiếu chéo giữa các phần của tài liệu.
Ngày 4 tháng 10 năm 2020 – Ngày 5 tháng 10 năm 2020: Thảo luận Tại thời điểm này, tức là trước khi chỉnh sửa tài liệu, tôi sẽ trình bày những phát hiện và kế hoạch của mình cho các cố vấn và nhóm liên quan. Ý kiến phản hồi của họ sẽ giúp bạn tinh chỉnh kế hoạch và điều chỉnh khi cần.
Ngày 6 tháng 10 năm 2020 – Ngày 20 tháng 10 năm 2020: Viết lại và chỉnh sửa Trong khoảng thời gian này, tôi sẽ chỉnh sửa và cập nhật các phần tài liệu cần chỉnh sửa. Một số phần của tài liệu cấu hình có thể được viết lại hoặc một số nội dung mới có thể được thêm vào. Giai đoạn này sẽ tập trung vào việc đảm bảo tài liệu là chính xác, mới nhất, linh hoạt và có thể tái sử dụng.
Ngày 21 tháng 10 năm 2020 – Ngày 25 tháng 10 năm 2020: Sửa lỗi và đường liên kết Trong giai đoạn này, tôi sẽ xem lại bài viết của mình để loại bỏ lỗi ngữ pháp và lỗi cấu trúc, đồng thời kiểm tra kỹ để đảm bảo tính chính xác. Tôi cũng sẽ thêm các đường liên kết và tài liệu tham khảo giữa các phần, theo IA, để đảm bảo rằng tài liệu tuân theo sơ đồ kiến thức được thiết kế trước đó.
Ngày 26 tháng 10 năm 2020 – ngày 31 tháng 10 năm 2020: Phiên bản cuối cùng để gửi Tôi sẽ liên kết tất cả các tệp Markdown, tạo mục lục và chia sẻ bản nháp với các cố vấn. Đây sẽ là bản thảo đầu tiên được gửi, ở dạng một gói hoàn chỉnh.
Ngày 1/11/2020 – 5/11/2020: Xem xét lần đầu Trong 5 ngày này, tôi sẽ thảo luận về bản nháp đầu tiên với các cố vấn. Tôi sẽ nhận ý kiến phản hồi của họ và thảo luận với họ về các ý tưởng của tôi để tạo danh sách nội dung cần chỉnh sửa.
Ngày 6 tháng 11 năm 2020 – ngày 12 tháng 11 năm 2020: Nội dung chỉnh sửa đầu tiên Nhờ có ý kiến phản hồi của các cố vấn, tôi sẽ chỉnh sửa bản thảo đầu tiên của tài liệu. Nội dung chỉnh sửa thực tế sẽ phụ thuộc vào bản chất của nhận xét và ý kiến phản hồi, nhưng mục tiêu sử dụng lại, độ chính xác và tính linh hoạt sẽ là tâm điểm của giai đoạn chỉnh sửa.
Ngày 13 tháng 11 năm 2020 – ngày 15 tháng 11 năm 2020: Xem xét lần thứ hai Sau khi hoàn tất các nội dung chỉnh sửa ban đầu, tôi sẽ thảo luận lại tiến trình với các cố vấn và nhóm liên quan. Các cuộc thảo luận này sẽ tập trung vào những nội dung chỉnh sửa đối với phiên bản đầu tiên, đồng thời nêu bật mọi vấn đề khác có thể phát sinh trong quá trình chỉnh sửa.
Ngày 16 tháng 11 năm 2020 – Ngày 19 tháng 11 năm 2020: Bản chỉnh sửa thứ hai Sau đó, tôi sẽ dành 4 ngày để chỉnh sửa tài liệu. Các phiên bản được tạo ra sẽ được thảo luận với các cố vấn để hoàn thiện. Khi hoàn tất giai đoạn này, các tài liệu sẽ ở dạng hoàn chỉnh, sẵn sàng để tải lên trang web và kho lưu trữ GitHub.
Ngày 20 tháng 11 năm 2020 – ngày 23 tháng 11 năm 2020: Tải lên trang web Sau khi bạn chỉnh sửa xong, các tài liệu sẽ được tải lên trang web. Mọi vấn đề gặp phải trong quá trình này sẽ được xử lý tương ứng vì chúng tôi vẫn còn vài ngày để xử lý tài liệu.
Ngày 24 tháng 11 năm 2020 – Ngày 28 tháng 11 năm 2020: Báo cáo dự án Báo cáo chi tiết về dự án sẽ được tạo trong khoảng thời gian 5 ngày này. Mục tiêu, khó khăn, vấn đề và giải pháp được trình bày sẽ là một phần của báo cáo dự án. Báo cáo sẽ được chia sẻ với những người cố vấn để lấy ý kiến phản hồi.
Ngày 29/11/2020 đến 30/11/2020: Gửi dự án cuối cùng Dự án cùng với tất cả tệp và báo cáo dự án sẽ được gửi cho các cố vấn. Chúng tôi sẽ tổ chức một cuộc họp/thảo luận với các cố vấn và các nhóm liên quan để xem xét toàn bộ dự án.
Trong suốt dự án, tôi sẽ tiếp tục tham khảo ý kiến của các cố vấn để nhận được ý kiến phản hồi có giá trị của họ. Bạn có thể thay đổi tất cả các mốc này dựa trên các cuộc thảo luận với cố vấn trong giai đoạn gắn kết cộng đồng và xem xét đề xuất.
Giới thiệu về tôi Tôi có bằng đại học về Kỹ thuật điện và bằng sau đại học về Truyền thông chuyên nghiệp và kỹ thuật của Đại học Bang Bắc Carolina. Tôi có kinh nghiệm trong các lĩnh vực viết và biên tập kỹ thuật và chuyên nghiệp, truyền thông và quản lý nội dung, nghiên cứu khả năng hữu dụng của web và thiết bị di động, cũng như thiết kế hướng dẫn. Tôi từng là Biên tập viên phụ cho một ấn phẩm trực tuyến (Global Làng Space) và là Thực tập sinh truyền thông cho Fair Forge tại Đại học Fair. Ngoài ra, tôi cũng quan tâm đến việc viết sáng tạo.