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ở:
- BRL-CAD
- Người viết nội dung kỹ thuật:
- sahibkaur
- Tên dự án:
- Hướng dẫn dành cho người mới bắt đầu về BRL-CAD
- Thời lượng dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Hướng dẫn dành cho người mới bắt đầu về BRL-CAD
Tóm tắt dự án
Dự án này nhằm tạo ra tài liệu dành riêng cho những người dùng không chỉ mới sử dụng BRL-CAD mà còn mới sử dụng nguồn mở.
Lý do của dự án này
Khi lần đầu tiên truy cập trang web của BRL-CAD, vì tôi mới sử dụng mã nguồn mở và BRL-CAD, nên tôi đã bị choáng ngợp bởi lượng thông tin trong một lần truy cập. Nhưng trong sâu thẳm, tôi biết có rất nhiều điều cần tìm hiểu ở đây. Vì vậy, tôi muốn tạo tài liệu cho những người dùng mới như tôi để hiểu rõ hơn về cộng đồng này và cảm thấy thoải mái khi bắt đầu.
Bàn thắng
Dự án này sẽ nhắm đến người dùng mới. Vì vậy, sau đây là một số điểm mà tài liệu của tôi hướng đến: Đảm bảo người dùng mới cảm thấy thoải mái: Vì tài liệu này dành cho người dùng mới không chỉ mới sử dụng BRL-CAD mà còn mới sử dụng nguồn mở.
Để đạt được điều này, tôi sẽ:
- Đảm bảo điểm Flesch-Kincaid của tài liệu ít nhất là 50. Theo phương pháp Flesch-Kincaid, điểm càng cao thì văn bản càng dễ hiểu. Bạn có thể kiểm tra điểm dễ đọc của văn bản đó trên mạng.
- Sử dụng danh sách có dấu đầu dòng hoặc danh sách có đánh số để người đọc không cảm thấy chán hoặc bị phân tâm bởi các đoạn văn dài.
- Sử dụng các đoạn văn và câu ngắn hơn vì việc đọc và hiểu các câu dài hơn đòi hỏi trí óc tương đối nhiều hơn.
- Sử dụng tiêu đề phụ để chia nhỏ văn bản. Tài liệu được sắp xếp hợp lý: Tài liệu được sắp xếp hợp lý đóng vai trò quan trọng trong việc hướng dẫn người dùng mới. Điều này giúp họ không bị lạc đường, đồng thời cho họ biết họ đang đi đâu và đang làm gì. Để làm được điều này, tôi đã tạo một sơ đồ tư duy sơ lược có thể giúp chúng ta ghi lại hướng dẫn dành cho người mới theo cách có tổ chức.
Mô tả dự án
Dự án này tập trung vào việc viết tài liệu để người dùng mới có thể làm quen với phần mềm này.
Dưới đây là ví dụ về cách tôi dự định làm cho tài liệu mô tả rõ ràng hơn.
Giới thiệu cơ bản: BRL-CAD (phát âm là be-are-el-cad) là một hình học khối xây dựng (CSG) lập mô hình khối dựa trên máy tính (CAD). Đây là một hệ thống lập mô hình vững chắc nguồn mở, đa nền tảng, mạnh mẽ dành cho thiết kế 3D với sự hỗ trợ của máy tính và trực quan hoá đồ hoạ. Bạn không hiểu rõ về vấn đề này? Cùng phân tích thật kỹ nào. Nguồn mở: Phần mềm nguồn mở là phần mềm có mã nguồn mà bất kỳ ai cũng có thể kiểm tra, sửa đổi và nâng cao. BRL-CAD là phần mềm nguồn mở hoan nghênh bạn đóng góp và giúp cải thiện BRL-CAD hiệu quả hơn trước! Thiết kế hỗ trợ máy tính (CAD): Nói một cách đơn giản, CAD là việc sử dụng các chương trình máy tính để tạo bản trình bày đồ hoạ hai hoặc ba chiều của các vật thể thực. Hệ thống mô hình rắn: BRL-CAD tập trung vào CAD mô hình rắn. Mô hình rắn khác với các hình thức mô hình hình học khác ở chỗ nhấn mạnh vào tính chính xác về mặt vật lý, mô tả đầy đủ không gian 3D. Phương thức này mô phỏng một đối tượng cả bên trong lẫn bên ngoài. Hình học rắn có cấu trúc (CSG): CSG cho phép biểu thị các mô hình phức tạp dưới dạng một loạt các phép toán Boolean giữa các đối tượng gốc. Các đối tượng rắn đơn giản nhất dùng để biểu diễn được gọi là đối tượng gốc. Để hiểu CSG ở cấp độ cơ bản, hãy truy cập tại đây.
*Như đã đề cập trong phần mô tả ý tưởng dự án: tài liệu sẽ trình bày tối thiểu về việc cài đặt cơ bản, mô tả tổng thể về các chức năng, nguyên tắc lập mô hình của BRL-CAD, cách sử dụng cơ bản các công cụ chính, lập mô hình, nhập/xuất, phân tích và kết xuất.
Dưới đây là phần giới thiệu ngắn gọn về cách tôi sẽ trình bày từng phần trong tài liệu.
- Cài đặt cơ bản: Tôi sẽ thêm hướng dẫn từng bước để cài đặt phần mềm BRL-CAD cùng với ảnh chụp màn hình bắt buộc. Hướng dẫn dành cho người mới là một nơi phù hợp để người dùng mới bắt đầu. Một số tính năng tôi thấy bị thiếu là:
- Các bước trong hướng dẫn dành cho người mới bắt đầu này không được đánh dấu đầu dòng hoặc đánh số. Việc có hướng dẫn từng bước kèm theo ảnh chụp màn hình ở cuối mỗi bước sẽ giúp người dùng dễ dàng theo dõi hướng dẫn hơn.
- Mô tả tổng thể về các tính năng: Phần này sẽ bao gồm tất cả các khu vực nơi BRL-CAD có thể hiển thị kỳ quan. Phương pháp biểu đồ sẽ là cách hiệu quả hơn để thu hút sự chú ý đến phần này.
- Nguyên tắc lập mô hình của BRL-CAD: Phần này sẽ cần được giải thích thêm vì người dùng có thể hiểu rõ hơn về BRL-CAD sau khi nắm rõ các nguyên tắc lập mô hình này.
- Cách sử dụng cơ bản các công cụ chính: Theo phần này, chúng tôi sẽ có các hướng dẫn riêng về các công cụ chính và cách sử dụng cơ bản. Đây sẽ là các hướng dẫn từng bước.
- Xuất/Nhập: Người dùng sẽ tìm hiểu về Thư viện chuyển đổi hình học. Một trong những cách sử dụng phổ biến nhất của BRL-CAD là chuyển đổi hình học từ định dạng này sang định dạng khác. Trong phần này, chúng ta sẽ thảo luận về trình chuyển đổi xuất và nhập.
- Kết xuất: Chúng ta sẽ tìm hiểu những kiến thức cơ bản về kết xuất và nhu cầu kết xuất trong phần mềm. Người dùng cũng sẽ tìm hiểu cách kết xuất hình ảnh trong BRL-CAD.
Ngoài ra, bạn cũng cần tập trung vào các điểm sau:
- Phần đầu tài liệu sẽ cung cấp thông tin cơ bản về phần mềm này.
- Cách người dùng có thể kết nối với cộng đồng nguồn mở này; đường liên kết đến cuộc trò chuyện trên Zulip về BRL-CAD.
- Ở mức độ trừu tượng, hãy làm cho tài liệu trở nên hài hước một chút và yêu cầu người dùng mới không làm họ nản lòng bởi những từ đa dạng. Tôi thích cách tiếp cận đồng cảm được sử dụng trên trang chính của BRL-CAD wiki.
- Phần mềm này sẽ có ảnh chụp màn hình về một số việc tuyệt vời mà người dùng có thể làm khi sử dụng phần mềm này.
Cột mốc
Tháng 7 (Khoảng thời gian xem xét đề xuất)
- Tôi sẽ làm quen hơn với phần mềm và tài liệu wiki của phần mềm đó trong khi xem các hướng dẫn hiện có.
- Tôi sẽ cải thiện tài liệu hiện có.
Ngày 1 tháng 8 – ngày 7 tháng 8 (Gắn kết cộng đồng)
- Thảo luận với người cố vấn về dự án.
- Tinh chỉnh thông tin chi tiết về dự án.
- Thực hiện các thay đổi bắt buộc trong các mốc quan trọng (nếu cần).
Từ ngày 8 tháng 8 đến ngày 14 tháng 8
- Làm quen với Docbook XML
Từ ngày 15 tháng 8 đến ngày 21 tháng 8
- Viết tài liệu cho phần "Giới thiệu cơ bản về BRL-CAD"
- Viết hướng dẫn từng bước cho phần "Cài đặt cơ bản"
Từ ngày 22 đến ngày 27 tháng 8
- Khám phá nhiều tính năng của BRL-CAD và liệt kê các tính năng đó cùng với ảnh chụp màn hình.
- Giải thích từng tính năng trên một trang riêng.
Ngày 28 tháng 8 – ngày 3 tháng 9
- Tiếp tục làm việc trên các tài liệu riêng lẻ cho các tính năng.
Từ ngày 4 đến ngày 10 tháng 9
- Làm việc trên Nguyên tắc lập mô hình.
- Giải thích tất cả các nguyên tắc lập mô hình.
Ngày 11 tháng 9 – ngày 17 tháng 9
- Làm việc về cách sử dụng cơ bản của các công cụ chính.
- Liệt kê ý tưởng để ghi lại cách sử dụng cơ bản của từng công cụ.
Từ ngày 18 tháng 9 đến ngày 24 tháng 9
- Ghi lại cách sử dụng từng công cụ.
Từ ngày 25 tháng 9 đến ngày 1 tháng 10
- Thực hành Lập mô hình để tạo mô hình vững chắc cho phần hướng dẫn và bên cạnh viết bản nháp.
Ngày 2 tháng 10 – ngày 8 tháng 10
- Cải thiện bản nháp lập mô hình.
Ngày 2 tháng 10 – ngày 8 tháng 10
- Nghiên cứu trình chuyển đổi xuất và nhập.
Ngày 9 tháng 10 – ngày 15 tháng 10
- Chuẩn bị tài liệu xuất và nhập.
- Bắt đầu xử lý việc kết xuất.
Từ ngày 16 tháng 10 đến ngày 22 tháng 10
- Ghi lại hướng dẫn kết xuất.
Từ ngày 23 tháng 10 đến ngày 29 tháng 10
- Xem xét tất cả tài liệu.
Từ ngày 30 tháng 10 đến ngày 5 tháng 11
- Xử lý tệp XML của Sổ tay tài liệu
Ngày 6 – 12 tháng 11
- Yêu cầu các cố vấn và thành viên khác trong cộng đồng đánh giá và điều chỉnh nội dung.
- Thảo luận với cố vấn và thực hiện những thay đổi cuối cùng.
Ngày 12 tháng 11 – ngày 22 tháng 11
- Quy trình thảo luận và thay đổi.
- Hoàn thiện tài liệu.
Giới thiệu về bản thân
Tôi đã yêu thích việc viết lách từ những ngày còn đi học. Tôi thường về nhà sau giờ học và viết tất cả về ngày của mình; những gì khiến ngày của tôi tốt hơn hoặc tệ hơn. Tôi luôn muốn ghi lại những lỗi mình mắc phải và cách khắc phục.
Trong quá trình đào tạo để trở thành nhà thiết kế web, chúng tôi được yêu cầu ghi lại những điều mình học được mỗi ngày. Tôi sẽ ghi lại một số vấn đề tôi gặp phải và giải pháp cho vấn đề đó.
Tôi luôn cố gắng hết sức để giúp đỡ người khác. Khi còn đi học, tôi thường giải thích một số chủ đề cho bạn bè sau khi tự hiểu những chủ đề đó. Tham gia GSoD là một bước tuyệt vời mà tôi, với tư cách là một người viết, có thể đóng góp vào việc làm cho cộng đồng nguồn mở này trở nên hấp dẫn và hữu ích hơn đối với người dùng mới trên toàn thế giới.