Projekt BRL-CAD

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.