Dự án ESLint

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

ESLint

Người viết nội dung kỹ thuật:

Tiếng Kawar

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 đích của dự án này là cơ cấu lại cấu trúc tài liệu về cấu hình cho ESLint và tạo ra một kiến trúc thông tin hiệu quả. Việc này sẽ giúp bạn dễ dàng điều hướ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 trên một trang. Mặc dù có tiêu đề, tiêu đề phụ và đoạn văn thích hợp trên trang, nhưng tài liệu có thể gây choáng ngợp. Không có cách nào để điều hướng đến một phần cụ thể của trang, 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 phục vụ mục đích và yêu cầu người dùng bỏ thêm công sức.

Tuy nhiên, các vấn đề này có thể được giải quyết bằng một loạt các bước cẩn thận. Bước đầu tiên trong quá trình tái sắp xếp này, tôi đề xuất kiểm tra nội dung. Quy trình kiểm tra nội dung không chỉ giúp xác định vấn đề trong cách 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 ra Kiến trúc thông tin (IA) để khám phá mạng tri thức. Việc này sẽ giúp chúng tôi nhóm thông tin theo nhiều 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 đó, toàn bộ gói có thể được liên kết và tham chiếu chéo trong Markdown. Do đó, sẽ có một 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 khá lâu, nhưng tôi vẫn khá mới mẻ 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 những lỗi nhỏ có thể làm rối toàn bộ mã. Tôi nghĩ sẽ tốt hơn nếu bạn được kiểm tra mã và xác định được các lỗi. Sau đó, tôi biết đến thuật ngữ "lint" (tìm lỗi mã nguồn). Tôi vốn chưa từng sử dụng phần mềm tìm lỗi mã nguồn, nhưng chắc chắn rằng những công cụ này sẽ giúp cuộc sống của tôi dễ dàng hơn rất nhiều trong tương lai.

Với kiến thức chuyên môn về Kỹ thuật điện và một số kinh nghiệm về lập trình, tôi có thể hiểu rõ hơn về các vấn đề về lập trình cũng như các yêu cầu của người lập trình. Ngoài ra, khi tốt nghiệp ngành Kỹ thuật và Giao tiếp chuyên nghiệp, tôi trở thành một người ủng hộ người dùng và cố gắng giúp mọi người trong cuộc sống dễ dàng hơn. Các kỹ năng và chuyên môn của tôi sẽ kết hợp hiệu quả cho dự án này và giúp tăng thêm giá trị cho tài liệu về ESLint.

Mục tiêu Mục tiêu chung 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 làm người dùng bị choáng ngợp. Điều quan trọng đối với sự thành công của dự án là việc điều hướng qua nội dung phải dễ dàng và không có tất cả chức năng. Sau đây là những 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 Kiến trúc thông tin để hiểu luồng thông tin – Cải thiện kiến trúc thông tin để sắp xếp lại tài liệu – Xác định đường liên kết và tham chiếu giữa các phần nội dung – Viết lại/Chỉnh sửa các phần của tài liệu, nếu cần để đáp ứng yêu cầu định 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 cho ESLint có thể tuỳ chỉnh được. 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. Do đó, điều quan trọng là cần phải hướng dẫn người dùng đế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 cấu hình cho ESLint chứa 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, thất vọng và mất phương hướng. Ví dụ: Nếu ai đó muốn tìm hiểu về cách sử dụng trình bổ trợ của bên thứ ba trong ESLint, họ sẽ phải di chuyển xuống dưới 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à tập lệnh toàn cục. Toàn bộ quá trình này làm người dùng nhàm chán và có thể khiến họ rời khỏi trang web. Tương tự như vậy, nếu người dùng ở đâu đó ở giữa trang và muốn chuyển đến một mục cụ thể hoặc chỉ để xem các chủ đề tương tự, thì đó không phải là một nhiệm vụ dễ dàng đối với họ vì không có sự hỗ trợ nào như vậy được cung cấp cho họ. Những vấn đề này cần được chú ý ngay lập tức vì chất lượng của bất kỳ tài liệu nào, cho dù được soạn thảo tốt đến mức nào, đều phụ thuộc vào tính hữu ích của tài liệu đó. Tôi đề xuất giải pháp cho các vấn đề này, cũng như các vấn đề khác có liên quan trong cuộc thảo luận tiếp theo.

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 về cấu hình là kiểm tra toàn diện nội dung. Mục đích của quá trình kiểm tra là xác định một số vấn đề chính như nội dung lỗi thời, nội dung trùng lặp, nội dung bị thiếu, v.v. Sau đó, một bảng tính kiểm tra nội dung mà bạn tạo sẽ được chia sẻ với nhóm quản lý và tài liệu để họ lấy ý kiến phản hồi của họ. Việc này giúp bạn nghĩ ra chiến lược mới để sắp xếp 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 tri thức hoặc luồng thông tin trong tài liệu về cấu hình, việc tạo cấu trúc thông tin (IA) có thể rất hữu ích. Các phát hiện trong quá trình kiểm tra nội dung sẽ là cơ sở tốt để hiểu 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 tốt hơn. Việc cải thiện IA này sẽ không chỉ tái cấu trúc nội dung hiện tại mà còn xác định các mối liên kết và nhánh phát triển giữa các phần khác nhau của tài liệu, nhờ đó tạo ra một mạng lưới hiệu quả. Ví dụ: theo sau nội dung trên phần “Định cấu hình quy tắc”, bạn có thể truy cập vào một đường liên kết dẫn đến mục “Vô hiệu hoá quy tắc có nhận xét cùng dòng”. Các đường liên kết khác như vậy cũng có thể được xác định, từ đó tạo ra mối quan hệ giữa các phần khác nhau của tài liệu.

Mục lục Kiểm tra nội dung và IA sẽ cung cấp thông tin đầy đủ để tạo mục lục chi tiết có các đường liên kết đến các phần và tiểu mục cụ thể của tài liệu. Việc tạo các tệp riêng biệt cho từng phần và thêm các tài liệu tham khảo thích hợp vào các phần khác có thể làm tăng thêm giá trị cho toàn bộ bộ tài liệu. Bạn có thể tạo mục lục cho những người dùng truy cập vào tài liệu về cấu hình, nhờ đó hỗ trợ họ trong quá trình sử dụng trang web. Mục lục có thể bao gồm tất cả tiêu đề cấp một và cấp hai để đảm bảo tính ngắn gọn nhưng toàn diện. Một ví dụ là phương pháp được 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 để mọi thứ trở nên đơn giản và được sắp xếp hợp lý. Hãy đặc biệt chú ý đến việc đảm bảo rằng tài liệu có thể tái sử dụng vì tài liệu đó có thể phát triển và thay đổi trong tương lai.

Công cụ nên sử dụng Một số công cụ quan trọng có thể hữu ích khi làm dự án: Draw.io để tạo hình minh hoạ cho IA khi 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 quản lý phiên bản của tài liệu

Các mốc quan trọng Từ khi gửi đề xuất cho đến khi hoàn thành dự án, các mốc dự kiến sau đây sẽ đảm bảo rằng dự án hoàn thành đúng hạn, duy trì đúng luồng trong quy trình.

10/7/2020 – 16/8/2020: Đánh giá và lựa chọn đề xuất Tôi sẽ xem qua 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.

17/8/2020 – 13/9/2020: Gắn kết cộng đồng Trong giai đoạn gắn kết cộng đồng, tôi sẽ điều chỉnh đề xuất của mình dựa trên các cuộc thảo luận với cố vấn và các 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 cũng sẽ liệt kê danh sách rút gọn các công cụ để dùng trong dự án.

14/9/2020 – 19/9/2020: Kiểm tra nội dung Để bắt đầu dự án, tôi sẽ kiểm tra toàn diện nội dung của tài liệu cấu hình. Mục tiêu là làm nổi bật những vấn đề về nội dung và cách trình bày nội dung.

20/9/2020 – 25/9/2020: Kiến 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 lưới tri thức theo cách dễ hiểu. Sau đó, việc này sẽ giúp cải thiện luồng thông tin.

26/9/2020 – 30/9/2020: Các đườ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 để xác định các đường liên kết và nội dung tham chiếu giữa các phần khác nhau của tài liệu. Tôi cũng sẽ lập một hệ thống phân cấp cho tất cả các nhóm, từ đó cải thiện IA trong quá trình này.

01/10/2020 – 03/10/2020: Bản đồ cuối cùng Với sự trợ giúp của các thông tin chi tiết thu được thông qua việc kiểm tra nội dung và IA, tôi sẽ tạo bản đồ cuối cùng để triển khai trong tài liệu về cấu hình đã sắp xếp lại. Bản đồ toàn diện này sẽ có một mục lục, hệ thống phân cấp các chủ đề, một danh sách các đường liên kết và tài liệu tham khảo chéo giữa các phần của tài liệu.

04/10/2020 – 05/10/2020: Thảo luận Tại thời điểm này, trước khi chỉnh sửa tài liệu, tôi sẽ trình bày phát hiện và lập kế hoạch với các cố vấn và các 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 nếu cần.

06/10/2020 – 20/10/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 những phần hồ sơ cần xuất bản. Có thể một số phần trong tài liệu cấu hình sẽ được viết lại hoặc thêm một số nội dung mới. Trọng tâm trong giai đoạn này là đảm bảo rằng tài liệu là chính xác, cập nhật, linh hoạt và có thể sử dụng lại.

21/10/2020 – 25/10/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 làm của mình để loại bỏ các lỗi ngữ pháp và cấu trúc, đồng thời kiểm tra kỹ bài làm của mình để đảm bảo tính chính xác. Theo IA, tôi cũng sẽ thêm đường liên kết và tài liệu tham khảo giữa các phần, để đảm bảo rằng tài liệu này tuân theo sơ đồ tri thức được xây dựng trước đó.

26/10/2020 – 31/10/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ố vấn. Bản thảo đầu tiên sẽ được gửi đi dưới dạng một gói hoàn chỉnh.

01/11/2020 – 05/11/2020: Buổi đánh giá đầu tiên Trong 5 ngày này, tôi sẽ thảo luận về bản nháp đầu tiên với những người cố vấn của mình. Tôi sẽ lắng nghe ý kiến phản hồi của họ và thảo luận ý tưởng của mình với họ để tạo một danh sách nội dung chỉnh sửa.

06/11/2020 – 12/11/2020: Chỉnh sửa lần đầu Với sự trợ giúp từ ý kiến phản hồi của các chuyên viên cố vấn, tôi sẽ chỉnh sửa bản nháp đầu tiên của tài liệu. Việc chỉnh sửa thực tế sẽ phụ thuộc vào bản chất của nhận xét và phản hồi, nhưng mục tiêu của việc sử dụng lại, độ chính xác và tính linh hoạt sẽ đóng vai trò là trung tâm của giai đoạn chỉnh sửa.

13/11/2020 – 15/11/2020: Đánh giá 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 tiến độ với các cố vấn và các nhóm có liên quan thêm một lần nữa. Các cuộc thảo luận này sẽ tập trung vào những chỉnh sửa được thực hiện đối với phiên bản đầu tiên và cũng nêu bật bất kỳ vấn đề nào khác có thể đã phát sinh trong quá trình chỉnh sửa.

16/11/2020 – 19/11/2020: Chỉnh sửa lần hai Sau đó, tôi sẽ dành thời gian 4 ngày để chỉnh sửa tài liệu này. Các phiên bản được tạo ra sẽ được thảo luận với những người cố vấn để cung cấp cho họ hình dạng cuối cùng. Khi hoàn thành giai đoạn này, tài liệu sẽ ở hình dạng cuối cùng và sẵn sàng để được tải lên trang web và kho lưu trữ GitHub.

20/11/2020 – 23/11/2020: Tải lên trang web Sau khi thực hiện tất cả các nội dung chỉnh sửa cần thiết, giấy tờ sẽ được tải lên trang web. Mọi vấn đề bạn gặp phải trong quá trình này đều được xử lý theo cách phù hợp vì chúng tôi vẫn sẽ có vài ngày để xử lý hồ sơ.

24/11/2020 – 28/11/2020: Báo cáo dự án Một báo cáo chi tiết về dự án sẽ được tạo trong khoảng thời gian 5 ngày. Các mục tiêu, khó khăn, vấn đề và giải pháp được trình bày sẽ tạo thành 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.

29/11/2020 – 30/11/2020: Gửi nội dung chính thức Dự án cùng với tất cả các tệp và báo cáo dự án sẽ được gửi cho các cố vấn. Việc đánh giá toàn bộ dự án sẽ được tiến hành thông qua cuộc họp/thảo luận với cố vấn và các nhóm có liên quan.

Trong suốt dự án, tôi sẽ tiếp tục tham khảo ý kiến của các cố vấn để thu thập ý kiến phản hồi có giá trị của họ. Tất cả những cột mốc này có thể thay đổi dựa trên cuộc thảo luận với cố vấn trong giai đoạn gắn kết cộng đồng và đánh giá đề xuất.

Giới thiệu về tôi Tôi có bằng đại học ngành Kỹ thuật điện và bằng tốt nghiệp về Kỹ thuật và truyền thông chuyên nghiệp của Đại học tiểu bang Bắc Carolina. Tôi có kinh nghiệm trong các lĩnh vực viết và chỉnh sửa kỹ thuật và chuyên nghiệp, quản lý nội dung và truyền thông, nghiên cứu khả năng sử dụng trên web và thiết bị di động cũng như thiết kế hướng dẫn. Tôi từng đảm nhiệm vai trò Biên tập viên phụ cho một ấn bản trực tuyến (Global Village Space) và Thực tập sinh truyền thông cho Fair Forge tại Đại học Fair. Cùng với đó, tôi cũng quan tâm đến việc viết sáng tạo.