Ta strona zawiera szczegółowe informacje na temat projektu dotyczącego pisania technicznego zaakceptowanego do udziału w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- BRL-CAD
- Pisarz techniczny:
- sahibkaur
- Nazwa projektu:
- BRL-CAD – przewodnik dla początkujących
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
BRL-CAD – przewodnik dla początkujących
Podsumowanie projektu
Ten projekt ma na celu opracowanie dokumentacji przeznaczonej dla użytkowników, którzy nie tylko dopiero zaczynają swoją przygodę z BRL-CAD, ale także rozpoczynają korzystanie z oprogramowania open source.
Dlaczego ten projekt
Kiedy pierwszy raz odwiedziłem witrynę BRL-CAD, gdy dopiero zaczynałem przygodę z oprogramowaniem open source i BRL-CAD, przytłoczyła mnie ilość informacji dostępnych za jednym razem. Jednak w głębszej wierze zdałam sobie sprawę, że można się tutaj wiele nauczyć. Zdecydowałam się więc przygotować dokumentację dla nowych użytkowników, takich jak ja. W ten sposób mogę ułatwić sobie pracę w tej społeczności.
Cele
Ten projekt będzie kierowany do nowych użytkowników. Oto kilka punktów, które powinna osiągnąć moja dokumentacja: Aby zapewnić nowym użytkownikom swobodę: ta dokumentacja jest przeznaczona nie tylko dla nowych użytkowników BRL-CAD, ale także dla nowych użytkowników open source.
Aby to osiągnąć:
- Pamiętaj, aby ocena Flescha-Kincaida dokumentu wynosiła co najmniej 50. Według metody Flescha-Kincaida im wyższy wynik, tym łatwiej zrozumieć fragment. Wynik jego czytelności możesz sprawdzić online.
- Używaj list punktowanych lub numerowanych, aby długie akapity nie były nudne i nie rozpraszały czytelników.
- Używaj krótszych akapitów i zdań, ponieważ czytanie i rozumienie dłuższych zdań wymaga trochę więcej pracy umysłowej.
- Użyj podtytułów, aby podzielić tekst. Uporządkowana dokumentacja: odpowiednio uporządkowana dokumentacja odgrywa kluczową rolę w kierowaniu nowych użytkowników. Dzięki temu nie zagubią się i informują, dokąd zmierzają i co robią. Aby to osiągnąć, stworzyłam mapę myśli, która może pomóc w uporządkowanym udokumentowaniu przewodnika dla początkujących.
Opis projektu
Ten projekt obejmuje przygotowanie dokumentacji dla nowych użytkowników, które pozwolą im zapoznać się z tym oprogramowaniem.
Poniżej znajduje się przykład, jak zamierzam dodać bardziej opisową dokumentację.
Wprowadzenie: BRL-CAD (wymowa be-are-el-cad) to konstrukcja oparta na konstrukcji stałej geometrycznej (CSG) modelująca konstrukcję wspomaganą komputerowo (CAD). Jest to zaawansowany, wieloplatformowy system open source do modelowania bryłowego do projektowania graficznego i wspomaganego komputerowo 3D. Nie wiesz, jak to zrobić? Przeanalizujmy wszystko po kolei. Otwarty kod źródłowy: oprogramowanie typu open source to oprogramowanie zawierające kod źródłowy, który każdy może sprawdzać, modyfikować i ulepszać. BRL-CAD to oprogramowanie open source. Zachęcamy do wzięcia udziału w programie i ulepszania go niż do tej pory. Projektowanie wspomagane komputerowo (CAD): najprościej mówiąc, CAD oznacza wykorzystanie programów komputerowych do tworzenia dwu- lub trójwymiarowej graficznej reprezentacji obiektów fizycznych. System modelowania stałego Symuluje obiekt zarówno wewnętrznie, jak i zewnętrznie. Konstruktywna geometria bryłowa (CSG): CSG umożliwia przedstawianie złożonych modeli jako serii operacji logicznych na elementach podstawowych. Najprostsze obiekty stałe używane do reprezentacji są nazywane elementami podstawowymi. Aby dowiedzieć się więcej o CSG na poziomie podstawowym, przejdź tutaj.
*Jak wspomniano w opisie projektu: Dokumentacja będzie w minimalnym stopniu obejmować podstawową instalację, ogólny opis możliwości, zasady modelowania BRL-CAD, podstawowe zastosowania głównych narzędzi, modelowanie, import i eksport, analizę i renderowanie.
To będzie krótkie wprowadzenie do tego, jak omówię każdą część dokumentacji.
- Instalacja podstawowa: dodam krok po kroku samouczek instalacji oprogramowania BRL-CAD wraz z wymaganymi zrzutami ekranu. Samouczek dla początkujących jest dobrym miejscem dla początkujących. Oto kilka rzeczy, których brakuje:
- Kroki tego samouczka dla początkujących nie są punktowane ani numerowane. Szczegółowy samouczek ze zrzutem ekranu na końcu każdego kroku zwiększa prawdopodobieństwo przyzwyczajenia użytkownika do treści.
- Ogólny opis możliwości: ta sekcja obejmuje wszystkie obszary, w których BRL-CAD może prezentować cuda. Lepszym sposobem na przykucie uwagi do tej części będzie diagram.
- Zasady modelowania BRL-CAD: ta część będzie wymagała dokładniejszego wyjaśnienia, ponieważ użytkownik będzie mógł lepiej zrozumieć model BRL-CAD, gdy zrozumie te zasady.
- Podstawowe korzystanie z głównych narzędzi: tutaj udostępnimy oddzielne samouczki dotyczące głównych narzędzi i ich podstaw. Będą to samouczki krok po kroku.
- Eksportuj/importuj: użytkownicy poznają bibliotekę konwersji geometrycznych. Jednym z najczęstszych zastosowań BRL-CAD jest konwersja geometrii z jednego formatu na inny. W tej sekcji omawiamy narzędzia do eksportowania i importowania danych o konwersjach.
- Renderowanie: omówimy podstawy renderowania oraz jego potrzebę w naszym oprogramowaniu. Użytkownicy dowiedzą się też, jak renderować obrazy w BRL-CAD.
Warto też skupić się na następujących kwestiach:
- Na początku dokumentacji wyjaśniamy, jak działa to oprogramowanie.
- Jak użytkownicy mogą nawiązać kontakt z tą społecznością open source; link do czatu BRL-CAD zulip.
- Na poziomie abstrakcyjnym zadbanie o to, aby dokumentacja była trochę humorystyczna, i zachęcenie nowych użytkowników, by nie zniechęcali się wielkimi słowami. Spodobało mi się empatyczne podejście na stronie głównej wiki BRL-CAD.
- Będą tam zrzuty ekranu pokazujące niesamowite rzeczy, które użytkownicy mogą robić przy użyciu tego oprogramowania.
Cele
Lipiec (okres sprawdzania oferty pakietowej)
- Będę się lepiej zapoznawała z oprogramowaniem i jego dokumentami wiki, analizując istniejące samouczki.
- Wprowadzę ulepszenia w istniejących dokumentach.
1–7 sierpnia (powiązania ze społecznością)
- Rozmowy z mentorami na temat projektu.
- Doprecyzowywanie szczegółów projektu.
- W razie potrzeby wprowadź wymagane zmiany w etapach milowych.
8–14 sierpnia
- Zapoznaj się z plikiem XML w Docbooku
15–21 sierpnia
- Opracowanie dokumentacji „Podstawowe wprowadzenie do BRL-CAD”
- Tworzenie szczegółowego samouczka dotyczącego „instalacji podstawowej”
22–27 sierpnia
- Omówienie różnych możliwości BRL-CAD i ich zestawienie wraz ze zrzutami ekranu.
- Objaśnij poszczególne funkcje na osobnej stronie.
28 sierpnia – 3 września
- Kontynuuj pracę nad poszczególnymi dokumentami, aby poznać możliwości.
4–10 września
- Praca nad zasadami modelowania.
- Objaśnienie wszystkich zasad modelowania.
11–17 września
- Ćwiczenie z podstawami korzystania z głównych narzędzi.
- Utwórz listę pomysłów na podstawowe informacje o korzystaniu z każdego z narzędzi.
18–24 września
- Dokumentowanie użycia każdego narzędzia
25 września – 1 października
- Pracuj nad modelowaniem, aby utworzyć model kompletny na potrzeby samouczka, i napisz wersję roboczą.
2–8 października
- Ulepsz wersję roboczą modelowania.
2–8 października
- Analizuję osoby, które dokonały konwersji związanej z eksportem i importowaniem
9–15 października
- Przygotuj dokumenty do eksportowania i importowania.
- Zacznij pracę nad renderowaniem.
16–22 października
- Tworzę dokumentację samouczka renderowania.
23–29 października
- Przeglądanie wszystkich dokumentów.
30 października – 5 listopada
- Praca nad plikiem XML Docbooka
6–12 listopada
- Poproś mentorów oraz innych członków społeczności o opinie i popracuj nad zmianami.
- Rozmowy z mentorami i wprowadzanie ostatecznych zmian.
12–22 listopada
- Proces dyskusji i zmian.
- Na koniec uzupełnimy dokumentację.
O mnie
Piszę od czasów szkoły. Wracałam do szkoły i opisywałam o swoim dniu. Co sprawiło, że mój dzień stał się lepszy lub gorszy. Zawsze chciałam spisywać błędy, które popełniłam, i jak mogę je poprawić.
Podczas mojego szkolenia jako projektanta stron internetowych poproszono nas o zapisanie tego, czego się uczymy na co dzień. Udokumentowałbym pewne napotkane przeze mnie problemy i ich rozwiązania.
Jako człowiek zawsze staram się pomagać innym. Gdy na lekcjach i na uczelniach, po zapoznaniu się z nimi samodzielnie wyjaśniam pewne tematy znajomym, wyjaśniam je znajomym. Udział w GSoD to wspaniały krok, na którym ja, jako autorka, mogę przyczynić się do tego, by społeczność open source była bardziej atrakcyjna i pomocna dla nowych użytkowników z całego świata.