Ta strona zawiera szczegóły projektu technicznego do pisania w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- National Resource for Network Biology (NRNB)
- Pisarz techniczny:
- Prubhtej_9
- Nazwa projektu:
- Twórz dokumentację użytkownika SynBioHub i twórz samouczki dotyczące konkretnych przypadków użycia
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Streszczenie
Dokumentacja dla użytkownika ma na celu pomoc użytkownikom w korzystaniu z produktu lub usługi. Dobra dokumentacja dla użytkowników jest bardzo ważna, ponieważ pozwala im dowiedzieć się, jak korzystać z oprogramowania, jego funkcji, a także zawiera wskazówki i porady oraz rozwiązuje typowe problemy występujące podczas korzystania z oprogramowania. Obniża też koszty obsługi klienta i stanowi element tożsamości korporacyjnej produktu, ponieważ dobra dokumentacja użytkownika jest oznaką dobrego produktu i zespołu programistów. Bez dobrej dokumentacji użytkownik może nie wiedzieć, jak skutecznie i efektywnie wykonywać wymienione powyżej czynności. Dokumentacja dla użytkowników może odgrywać kluczową rolę w zapewnieniu sukcesu produktu, ponieważ skuteczna komunikacja zawsze będzie podstawą każdej firmy lub produktu. Dobra dokumentacja to nic innego jak komunikacja w ramach łatwych do zarządzania struktur, do których każdy może mieć dostęp. SynBioHub to repozytorium projektów z zakresu biologii syntetycznej. Jest ona dostępna jako publiczna witryna internetowa i oprogramowanie open source. SynBioHub używa otwartego języka do syntetycznej biologii (SBOL), czyli standardu open source do przedstawiania projektów genetycznych. Umożliwia też udostępnianie części projektów z plików GenBank i FASTA. SynBioHub można używać do publikowania biblioteki syntetycznych części 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ć za pomocą interfejsu HTTP API, Java API lub Python API, gdzie można je zintegrować z narzędziami CAD do tworzenia projektów genetycznych. SynBioHub zawiera interfejs, który umożliwia 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óżne publikacje naukowe i samouczki, np. 1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub zawiera pewną dokumentację, która dotyczy tylko interfejsu API, ale nie interfejsu graficznego.
Obecny stan dokumentacji:
Obecnie dokumentacja użytkownika jest dostępna na stronie :“https://synbiohub.github.io/api-docs/#about-synbiohub ”. Nie ma też dokumentacji interfejsu API, która może pomóc użytkownikowi poruszać się po repozytorium projektu. Dokumentacja interfejsu API wymaga też pewnych aktualizacji, np. w zakresie konkretnych tematów, takich jak rozwiązywanie problemów, które mogą napotkać użytkownicy. Organizacja nagrała kilka samouczków, takich jak ten. Nie ma żadnej pisemnej dokumentacji SynBioHub, która mogłaby służyć jako przewodnik dla użytkowników.
Dlaczego proponowana przez Ciebie dokumentacja użytkownika jest lepsza od obecnej? Będę tworzyć dokumentację GUI od podstaw, korzystając z GitHuba i Markdowna zgodnie z sugestiami mentora Chrisa Myersa. Proponowana dokumentacja użytkownika będzie uporządkowana w sposób zapewniający wydajność, spójność i bezpieczeństwo dla każdego użytkownika. Będzie on zawierał przewodniki w formie tekstu i powiązanych z nimi obrazów, a także instrukcje i wyjaśnienia dotyczące korzystania z każdej funkcji symulatora SynBioHub, który jest dostępny na zasadach open source. Podczas rozmów z panem Myersem zdecydowano także, że dokumentacja API zostanie połączona z GUI i będzie zawierać 6 sekcji, z których szósta będzie opcjonalna. Sekcje są wymienione w taki sposób: 1. Wprowadzenie 2. Instrukcje instalacji a) Z gotowego obrazu b) Z źródła c) Konfiguracja NGINX 3. Instrukcje dla użytkowników a) Szczegółowe instrukcje korzystania z każdej funkcji interfejsu graficznego b) Samouczki dotyczące typowych zastosowań 4. Dokumentacja interfejsu API – sekcja 5 dotycząca punktów końcowych. Dokumentacja wtyczki 6. Rozwiązywanie problemów i przykłady do wykorzystania w przyszłości.
Część 1.
W tej sekcji użytkownicy otrzymają szczegółowe wprowadzenie i różne samouczki dotyczące SynBioHub.
Część 2:
W tej sekcji omówiono różne sposoby instalowania oprogramowania open source za pomocą różnych metod, a mianowicie: a) z gotowego obrazu b) ze źródła c) konfiguracja NGINX
Część 3.
Jest to najważniejsza część dokumentacji i zajmuje najwięcej czasu. Szczegóły o każdej minucie zostaną tu dodane w kontekście do GUI. Jak już wspomnieliśmy, w tej sekcji znajdziesz głównie 2 rodzaje informacji: szczegółowe instrukcje korzystania z każdej funkcji interfejsu graficznego oraz samouczki dotyczące typowych zastosowań.
Część 4.
Jak już wspomnieliśmy, do wygenerowania dokumentacji tej części zostanie użyta skryptowa linia kodu. W tej sekcji uwzględniono te punkty końcowe: 1. Punkty końcowe użytkownika: Punkty końcowe wyszukiwania 3. Punkty końcowe pobierania4. Punkty końcowe pobierania 5. Punkty końcowe przesyłania danych 6. Punkty końcowe uprawnień. 7. Edytuj punkty końcowe 8. Punkty końcowe załączników 9. Punkty końcowe administracyjne
Część 5.
W tej sekcji znajdziesz dokumentację wtyczki, która jest już dostępna w starej dokumentacji SynBioHub. Ta sekcja będzie podzielona na 2 części: specyfikacja wtyczki i implementacja. Część 6. [Opcjonalnie] Ta sekcja zawiera listę najczęstszych błędów, z którymi spotykają się użytkownicy, a także instrukcje rozwiązywania problemów. Zgodnie z rozmową z panem Myersem postanowiliśmy połączyć tę sekcję z sekcją wprowadzającą, jeśli nie będzie ona zbyt długa. Analiza Podczas rozmowy z Myersem zastanawialiśmy się, jak zaktualizować dotychczasową dokumentację i opracować nową dla interfejsu graficznego. W tych kilku wątkach sformułowaliśmy podstawowy układ nowej dokumentacji, o którym wspomniano powyżej, a szacowany harmonogram przedstawiliśmy na stronie 5 poniżej. Zgodnie z rozmową będę używać GitHuba i Markdowna do tworzenia dokumentacji w każdej sekcji, z wyjątkiem części 4, w której użyję Slate. Slate: – Slate pomaga tworzyć atrakcyjną, inteligentną i elastyczną dokumentację interfejsów API. Slate to narzędzie oparte na Ruby, które na podstawie zestawu plików Markdown generuje świetnie wyglądającą stałą stronę dokumentacji interfejsu API z 3 panelami. Został on stworzony przez programistę Roberta Lorda w 2013 roku, gdy miał 18 lat i był stażystą w firmie zajmującej się oprogramowaniem do planowania podróży „Tripit”. Wtedy przekonał swojego szefa, aby pozwolił mu udostępnić projekt jako projekt typu open source. Reszta to już historia. Oferuje ona te funkcje: • Prosty, intuicyjny interfejs – w Slate opis interfejsu API znajduje się po lewej stronie dokumentacji, a przykłady kodu – po prawej. Inspirowane dokumentami interfejsu API Stripe i PayPal. Slate jest elastyczny, więc wygląda świetnie na tabletach, telefonach, a nawet w wersji drukowanej. • Wszystko na jednej stronie – skończyły się czasy, gdy użytkownicy musieli przeszukiwać milion stron, aby znaleźć to, czego szukali. Slate umieszcza całą dokumentację na jednej stronie. Nie zaniedbaliśmy jednak możliwości łączenia. Gdy przewijasz stronę, hasz przeglądarki będzie się zmieniać, aby wskazywać najbliższy nagłówek, dzięki czemu linkowanie do konkretnego punktu w dokumentacji jest proste i naturalne. • Slate to tylko Markdown – gdy tworzysz dokumenty w Slate, piszesz w formacie Markdown, który jest prosty w edytowaniu i zrozumieniu. Wszystko jest napisane w języku Markdown – nawet przykłady kodu to tylko bloki kodu Markdown. • Napisanie przykładowego kodu w wielu językach – jeśli Twój interfejs API ma powiązania w kilku językach programowania, możesz łatwo przełączać się między nimi za pomocą kart. W dokumentach możesz odróżniać różne języki, podając nazwę języka u góry każdego bloku kodu, tak jak w przypadku sformatowanego Markdowna GitHuba. • Gotowe do użycia funkcje wyróżniania składni w ponad 100 językach bez konieczności konfigurowania. • automatyczny, płynnie przewijany spis treści po lewej stronie strony; Podczas przewijania wyświetla się Twoja bieżąca pozycja w dokumencie. Jest też szybki. W TripIt używamy Slate do tworzenia dokumentacji nowego interfejsu API, w którym nasz spis treści zawiera ponad 180 pozycji. Zadbaliśmy o to, aby wydajność była doskonała nawet w przypadku większych dokumentów. • Pozwól użytkownikom aktualizować dokumentację za Ciebie – domyślnie Twoja dokumentacja wygenerowana w postaci planszy jest domyślnie przechowywana w publicznym repozytorium GitHub. Oznacza to nie tylko, że otrzymasz bezpłatny hosting dla swoich dokumentów w usłudze GitHub Pages, ale też, że inni deweloperzy będą mogli łatwo wysyłać do Twoich dokumentów żądania pull, jeśli znajdą w nich literówki lub inne problemy. Jeśli nie chcesz korzystać z GitHuba, możesz hostować dokumenty gdzie indziej. • Obsługa odwrotnej Bardziej szczegółowy widok dokumentacji znajdziesz w sekcjach poniżej. Struktura proponowanej dokumentacji. Utworzyłem strukturę Przewodnika użytkownika SynBioHub, którą znajdziesz na stronie 2. Ta struktura została zaakceptowana i już zmodyfikowana przez pana Myersa. Cele projektu 1. Zmień strukturę dokumentacji. 2. zaktualizowanie dokumentacji pod kątem najnowszych wersji SynBioHub; 3. Usuń nieaktualne informacje. 4. Zmodyfikuj dokumentację użytkownika, aby była bardziej zrozumiała. 5. Dodaj do dokumentacji dla nowych autorów krótkie informacje o wymaganiach wstępnych, aby pomóc im lepiej zrozumieć podstawowe pojęcia z biologii i interfejs SynBioHub.