Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- National Resource for Network Biology (NRNB)
- Pisarz techniczny:
- Prubhtej_9
- Nazwa projektu:
- Twórz dokumentację dla użytkowników SynBioHub i twórz samouczki dotyczące konkretnych przypadków użycia
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
W skrócie
Dokumentacja dla użytkowników ma pomagać użytkownikom w korzystaniu z produktów lub usług. Dobra dokumentacja użytkownika jest bardzo ważna, ponieważ umożliwia użytkownikom nauczenie się korzystania z oprogramowania, jego funkcji, porad i wskazówek, a także rozwiązywania typowych problemów. Obniża też koszty pomocy i jest częścią tożsamości firmy, np. dobra dokumentacja dla użytkownika jest oznaką prawidłowego działania usługi i pracy zespołu programistów. Bez dobrej dokumentacji użytkownik może nie wiedzieć, jak skutecznie i efektywnie wykonywać wymienione powyżej czynności. Dokumentacja użytkownika może odegrać kluczową rolę w zapewnieniu sukcesu usługi, ponieważ dobra komunikacja to podstawa każdej firmy i produktu, a dobra dokumentacja pozwala z niej korzystać w łatwy sposób w użyciu dla każdego. SynBioHub to repozytorium projektów z dziedziny biologii syntetycznej. Jest ona dostępna zarówno jako witryna publiczna, jak i oprogramowanie open source. SynBioHub wykorzystuje Synthetic Biology Open Language (SBOL), standard open source do przedstawiania projektów genetycznych, a także umożliwia udostępnianie części projektowych z plików GenBank i FASTA. SynBioHub można wykorzystać do opublikowania biblioteki części syntetycznych i projektów jako usługi, udostępniania projektów współpracownikom oraz przechowywania projektów systemów biologicznych lokalnie. Dostęp do danych w SynBioHub można uzyskać przez interfejsy HTTP API, Java API lub Python API, gdzie można je zintegrować z narzędziami CAD w celu tworzenia projektów genetycznych. SynBioHub zawiera interfejs umożliwiający użytkownikom przesyłanie nowych danych biologicznych do bazy danych, wizualizację części DNA, wykonywanie zapytań w celu uzyskania dostępu do wybranych części oraz pobieranie SBOL, GenBank, FASTA itp. W internecie dostępne są również różne artykuły badawcze i niektóre samouczki:
Obecny stan dokumentacji:
Dokumentacja użytkownika jest obecnie dostępna na stronie „https://synbiohub.github.io/api-docs/#about-synbiohub ”. Jest to tylko dokumentacja interfejsu API, a nie istnieje dokumentacja GUI, która mogłaby ułatwić użytkownikowi poruszanie się po repozytorium projektów. Również dokumentacja interfejsu API wymaga zaktualizowania, uwzględniając konkretne tematy, takie jak rozwiązywanie określonych problemów, z którymi mogą się spotkać użytkownicy. Organizacja nagrała kilka samouczków wideo, takich jak ten tutaj. Nie istnieje żadna pisemna dokumentacja użytkownika na temat SynBioHub, która mogłaby pomóc użytkownikowi.
Dlaczego zaproponowana przez Ciebie dokumentacja dla użytkowników jest ulepszona w stosunku do obecnej? Opracuję od podstaw dokumentację GUI za pomocą githuba i markdowna, zgodnie z instrukcjami mentora, Chrisa Myersa. Opracowana dokumentacja dla użytkowników zostanie opracowana w celu poprawy jej wydajności, spójności i spokoju ducha. Będzie on zawierać pisemne przewodniki i powiązane z nimi obrazy, a także instrukcje i wyjaśnienie dotyczące korzystania z poszczególnych funkcji symulatora open source SynBioHub. Podczas rozmów z panem Myersem zadecydowano również, że dokumentacja interfejsu API zostanie scalona z GUI i będzie zawierać 6 sekcji, z których 6. będzie opcjonalna. Sekcje te są wymienione w następujący sposób: 1. Wprowadzenie 2. Instrukcje instalacji a) Z gotowego obrazu b) Ze źródła c) Konfiguracja NGINX 3. Instrukcje dla użytkownika a) Szczegółowe instrukcje korzystania z poszczególnych funkcji GUI. b) Samouczki dotyczące typowych przypadków użycia. 4. Dokumentacja API – sekcja 5. Dokumentacja wtyczki 6. Rozwiązywanie problemów i przyszłe odniesienia.
Część 1.
W tej sekcji użytkownicy zobaczą szczegółowe wprowadzenie i różne samouczki dotyczące SynBioHub.
Część 2.
W tej sekcji przedstawiliśmy różne metody instalacji oprogramowania open source, a) z gotowego obrazu, b) ze źródła, c) konfigurację NGINX.
Część 3.
To najważniejsza część dokumentacji, która zajmie większość czasu. Każdy szczegół zostanie tu dodany w kontekście GUI. Jak już wspomnieliśmy, w tej sekcji omówimy głównie 2 problemy, tj. szczegółowe instrukcje korzystania z poszczególnych funkcji GUI oraz samouczki dotyczące typowych przypadków użycia.
Część 4.
Jak wspomniano powyżej, do wygenerowania dokumentacji tej części zostanie użyta plansza. W tej sekcji zostaną uwzględnione następujące punkty końcowe: 1. Punkty końcowe użytkownika 2. Wyszukaj punkty końcowe. 3. Pobierz punkty końcowe. 4. Pobierz punkty końcowe. 5. Punkty końcowe przesyłania 6. Punkty końcowe uprawnień. 7. Edytuj punkty końcowe. 8. Punkty końcowe załączników. 9. Punkty końcowe administratora
Część 5.
W tej sekcji zostanie dołączona dokumentacja wtyczki, która jest już dostępna w starej dokumentacji SynBioHub. Ta sekcja będzie podzielona na 2 części: specyfikacja wtyczki i jej implementacja. Część 6: [opcjonalnie] Ta sekcja będzie zawierać listę typowych błędów napotykanych przez użytkowników oraz instrukcje dotyczące rozwiązywania problemów. Na podstawie dyskusji z panem Myersem uznaliśmy, że tę sekcję można połączyć z sekcją z wprowadzeniem, jeśli nie zadłuży się ona na zbyt długim czasie. Rozmawialiśmy z Panem/Panią Myers na temat tego, jak zaktualizować istniejącą dokumentację oraz jak napisać nową dokumentację GUI. W tych kilku rozmowach opracowaliśmy podstawowy układ nowej dokumentacji, o którym wspomnieliśmy wyżej, a na stronie 5 poniżej podano jego szacowany harmonogram. Podczas rozmowy użyję github i markdown do tworzenia dokumentacji do wszystkich sekcji z wyjątkiem części 4, w których będzie używana plansza. Slate:– Slate pomaga tworzyć atrakcyjną, inteligentną i elastyczną dokumentację API. Slate to narzędzie w języku Ruby, które na podstawie zestawu plików Markdown generuje atrakcyjną, 3-panelową, statyczną witrynę z dokumentacją interfejsu API. Został on stworzony przez Roberta Lorda w 2013 roku, gdy był 18-letnim stażystą w firmie oferującej oprogramowanie turystyczne „Tripit”. Przekonywał wtedy swojego szefa, by pozwolił mu udostępnić projekt na licencji open source, a reszta to już historia. Zalety aplikacji: • przejrzysty, intuicyjny interfejs – w Slate; opis interfejsu API znajdziesz po lewej stronie dokumentacji, a wszystkie przykłady kodu – po prawej. Zainspirowane dokumentami Stripe i PayPal. Tabliczka jest elastyczna, więc wygląda świetnie na tabletach, telefonach, a nawet w druku. • Wszystko na jednej stronie – Minęły już czasy, gdy użytkownicy musieli przeszukiwać milion stron w celu znalezienia tego, czego szukali. Slate umieszcza całą dokumentację na jednej stronie. Nie rezygnowaliśmy jednak z możliwości łączenia. Podczas przewijania skrót przeglądarki jest aktualizowany do najbliższego nagłówka, więc linkowanie do określonego punktu w dokumentacji jest nadal naturalne i łatwe. • Slate to po prostu format Markdown. Pisząc dokumenty w Slate, piszesz po prostu o formacie Markdown, co ułatwia ich edytowanie i interpretowanie. Wszystko jest pisane w formacie Markdown – nawet fragmenty kodu są tylko blokami kodu tego formatu. • Napisać przykłady kodu w kilku językach – jeśli Twój interfejs API ma powiązania w wielu językach programowania, możesz łatwo umieścić karty w celu przełączania się między nimi. W dokumencie możesz rozróżniać języki, podając nazwę języka u góry każdego bloku kodu, tak jak w przypadku języka GitHub Flavored Markdown. • Gotowe podświetlenie składni w ponad 100 językach, bez konieczności konfigurowania. • Automatyczny, płynnie przewijany spis treści na skraju lewej części strony. Podczas przewijania wyświetlana jest bieżąca pozycja dokumentu. Poza tym jest szybki. Wykorzystujemy Slate w firmie TripIt do tworzenia dokumentacji nowego interfejsu API, w którym spis treści zawiera ponad 180 pozycji. Zagwarantowaliśmy doskonałą wydajność nawet w przypadku większych dokumentów. • Pozwól użytkownikom aktualizować dokumentację za Ciebie – dokumentacja wygenerowana w planach jest domyślnie hostowana w publicznym repozytorium GitHub. Oznacza to nie tylko bezpłatny hosting dokumentów na stronach GitHub, ale także ułatwia innym programistom wykonywanie żądań pull do Twoich dokumentów w przypadku literówek lub innych problemów. Oczywiście jeśli nie chcesz korzystać z GitHuba, możesz przechowywać swoje dokumenty gdzie indziej. • Obsługa od prawej do lewej w pełnym układzie tekstu od prawej do lewej w językach od prawej do lewej, takich jak arabski, perski (Farsi), hebrajski itp. Verdict Slate jest jednym z najpotężniejszych oprogramowania open source do generowania dokumentacji. Zgodnie z rozmowami z mentorem, Chrisem Myersem, w części 4 będę używać Slate i w innych częściach – github i markdown. Bardziej szczegółowy widok dokumentacji został omówiony w sekcjach poniżej. Struktura proponowanej dokumentacji została utworzona przeze mnie na potrzeby Przewodnika użytkownika SynBioHub, który można znaleźć na stronie 2. Ta struktura została zaakceptowana i została już zmodyfikowana przez użytkownika Myers . Cele projektu 1. Zmień strukturę dokumentacji. 2. Zaktualizuj dokumentację, aby dopasować ją do nowoczesnych wersji SynBioHub. 3. Usuń nieaktualne informacje. 4. Przeredaguj dokumentację użytkownika tak, aby była bardziej zrozumiała. 5. W dokumentacji dla nowych współtwórców dodaj krótką sekcję, w której będą spełniać wymagania wstępne, aby lepiej poznać podstawowe pojęcia biologiczne i sposób interfejsu SynBioHub.