Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione di Documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- National Resource for Network Biology (NRNB)
- Redattore tecnico:
- Prubhtej_9
- Nome del progetto:
- Creare la documentazione utente per SynBioHub e sviluppare tutorial per casi d'uso specifici
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Abstract
La documentazione per gli utenti ha lo scopo di aiutare gli utenti finali a utilizzare un prodotto o servizio. Una buona documentazione utente è molto importante perché offre agli utenti un modo per imparare a utilizzare un software, le sue funzionalità, suggerimenti e trucchi e anche per risolvere i problemi comuni riscontrati durante l'utilizzo del software. Inoltre, riduce i costi di assistenza e fa parte dell'identità aziendale del prodotto, ovvero una buona documentazione utente è un segno di un prodotto e di un team di sviluppatori sani. Senza una buona documentazione utente, un utente potrebbe non sapere come eseguire le operazioni sopra menzionate in modo efficace ed efficiente. La documentazione utente può svolgere un ruolo fondamentale per garantire il successo di un prodotto perché una comunicazione efficace è e sarà sempre al centro di qualsiasi attività o prodotto e una buona documentazione prende questa comunicazione e la inserisce in un framework gestibile a cui tutti possono accedere per ottenere risultati. SynBioHub è un repository di design per la biologia sintetica. È disponibile sia come sito web pubblico sia come software open source. SynBioHub utilizza il linguaggio SBOL (Synthetic Biology Open Language), uno standard open source per la rappresentazione dei progetti genetici, e consente anche di condividere parti del progetto da file GenBank e FASTA. SynBioHub può essere utilizzato per pubblicare una libreria di parti sintetiche e disegni come servizio, per condividere i progetti con i collaboratori e archiviare i progetti di sistemi biologici localmente. È possibile accedere ai dati di SynBioHub tramite l'API HTTP, l'API Java o l'API Python, dove possono essere integrati negli strumenti CAD per la creazione di progetti genetici. SynBioHub contiene un'interfaccia in cui gli utenti possono caricare nuovi dati biologici nel database o caricare nuovi dati biologici nel database, visualizzare le parti del DNA, visualizzare le parti del DNA, visualizzare le parti del DNA, eseguire query per accedere alle parti desiderate e scaricare SBOL, GenBank, FASTA, ecc..
Stato attuale della documentazione:
Al momento, la documentazione utente è disponibile all'indirizzo "https://synbiohub.github.io/api-docs/#about-synbiohub". Si tratta solo della documentazione dell'API e non esiste la documentazione della GUI che può aiutare l'utente a navigare nel repository dei progetti. Anche la documentazione dell'API richiede un po' di aggiornamento, con alcuni argomenti specifici come la risoluzione di determinati problemi peculiari che un utente può incontrare. L'organizzazione ha registrato alcuni video tutorial, come quello che trovi qui. Non esiste alcuna documentazione scritta per gli utenti di SynBioHub che possa fornire indicazioni.
Perché la documentazione utente proposta è un miglioramento rispetto a quella attuale? Realizzerò la documentazione della GUI da zero utilizzando GitHub e Markdown, come suggerito dal mio mentore, Chris Myers. La documentazione utente proposta sarà strutturata per migliorare e garantire efficienza, coerenza e tranquillità a qualsiasi utente finale. Conterrà guide scritte e le relative immagini associate, nonché istruzioni e spiegazioni su come utilizzare ogni funzionalità del simulatore open source SynBioHub. Durante le discussioni con il signor Myers, è stato deciso anche che la documentazione dell'API verrà unita alla GUI e conterrà sei sezioni, di cui la sesta sarà facoltativa. Le sezioni sono indicate come segue: 1. Introduzione 2. Istruzioni di installazione a) Dall'immagine predefinita b) Dall'origine c) Configurazione NGINX 3. Istruzioni per l'utente a) Istruzioni dettagliate su come utilizzare ciascuna funzionalità GUI b) Tutorial per casi d'uso comuni 4. Documentazione dell'API - sezione 5 relativa agli endpoint. Documentazione del plug-in 6. Risoluzione dei problemi e riferimenti futuri.
Parte 1:
In questa sezione, agli utenti verrà fornita un’introduzione dettagliata e vari tutorial relativi a SynBioHub.
Parte 2:
In questa sezione vengono descritti i vari modi in cui l'utente può installare il software open source utilizzando vari metodi, ovvero: a) Da un'immagine precompilata b) Da sorgente c) Configurazione di NGINX
Parte 3:
Questa è la parte più importante della documentazione e richiederà la maggior parte del tempo. Nel presente documento, ogni singolo dettaglio verrà aggiunto nel contesto della GUI. Come già accennato, principalmente due problemi verranno affrontati in questa sezione, ovvero le istruzioni dettagliate su come utilizzare ciascuna funzionalità GUI e alcuni tutorial per i casi d'uso comuni.
Parte 4:
Come accennato in precedenza, Slate verrà utilizzato per generare la documentazione di questa parte. In questa sezione saranno inclusi i seguenti endpoint: 1. Endpoint utente 2. Endpoint di ricerca 3. Scarica Endpoints 4. Scarica Endpoints 5. Endpoint di invio 6. Endpoint di autorizzazione. 7. Modifica endpoint 8. Endpoint di collegamento 9. Endpoint di amministrazione
Parte 5:
In questa sezione verrà inclusa la documentazione del plug-in già presente nella vecchia documentazione di SynBioHub. Questa sezione sarà suddivisa in due sezioni, ovvero: specifica del plug-in e implementazione. Parte 6: [Facoltativa] Questa sezione includerà un elenco molto comune di errori riscontrati dagli utenti e alcune istruzioni per la risoluzione dei problemi. In base alla discussione con il signor Myers, è stato deciso che questa sezione può essere unita alla sezione introduttiva, se non diventa troppo lunga. Analisi Il signor Myers e io abbiamo parlato di come aggiornare la documentazione esistente e anche di come scriverne una nuova per l'interfaccia utente. In queste poche conversazioni abbiamo formulato un layout di base per la nuova documentazione menzionata sopra e abbiamo fornito una tempistica stimata nella pagina 5 di seguito. Come da discussione, utilizzerò GitHub e Markdown per creare la documentazione per ogni sezione, ad eccezione della Parte 4, in cui verrà utilizzato Slate. Slate:- Slate ti aiuta a creare una documentazione API bella, intelligente e reattiva. Slate è uno strumento basato su Ruby che genera un sito statico di documentazione dell'API con tre riquadri dall'aspetto accattivante da un insieme di file Markdown. È stato realizzato dallo sviluppatore Robert Lord nel 2013, quando era uno stagista di 18 anni presso l'azienda di software di viaggio "Tripit". Ha convinto il suo capo all'epoca a lasciargli il progetto open source e il resto è storia. Presenta le seguenti funzionalità: • Design pulito e intuitivo: con Slate, la descrizione dell'API si trova sul lato sinistro della documentazione e tutti gli esempi di codice si trovano sul lato destro. Ispirato alla documentazione delle API di Stripe e PayPal. Lo slate è reattivo, quindi viene visualizzato al meglio su tablet, smartphone e persino sulla stampa. • Tutto in un'unica pagina: sono finiti i tempi in cui gli utenti dovevano cercare in un milione di pagine per trovare ciò che cercavano. Slate inserisce l'intera documentazione in una singola pagina. Tuttavia, non abbiamo sacrificato la collegabilità. Mentre scorri, l'hash del browser viene aggiornato all'intestazione più vicina, quindi il collegamento a un punto specifico della documentazione rimane semplice e intuitivo. • Slate è solo Markdown: quando scrivi documenti con Slate, scrivi solo Markdown, il che semplifica la modifica e la comprensione. Tutto è scritto in Markdown, anche gli esempi di codice sono solo blocchi di codice Markdown. • Scrivi esempi di codice in più lingue: se la tua API ha associazioni in più linguaggi di programmazione, puoi inserire facilmente schede per passare da una all'altra. Nel documento, distinguerai le diverse lingue specificando il nome della lingua nella parte superiore di ogni blocco di codice, proprio come con GitHub Flavored Markdown. • Evidenziazione della sintassi pronta all'uso per oltre 100 lingue, senza alcuna configurazione richiesta. • Sommario automatico con scorrimento fluido sulla sinistra della pagina. Mentre scorri, viene visualizzata la tua posizione corrente nel documento. Ed è veloce. Utilizziamo Slate su TripIt per creare la documentazione per la nostra nuova API, il cui sommario contiene più di 180 voci. Abbiamo fatto in modo che le prestazioni rimangano eccellenti, anche per i documenti più grandi. • Consenti agli utenti di aggiornare la documentazione per te: per impostazione predefinita, la documentazione generata da Slate è ospitata in un repository GitHub pubblico. Questo non solo significa che ottieni l'hosting senza costi per i tuoi documenti con le Pagine GitHub, ma consente anche ad altri sviluppatori di effettuare facilmente richieste di pull ai tuoi documenti se rilevano errori di battitura o altri problemi. Se non vuoi utilizzare GitHub, puoi anche ospitare i tuoi documenti altrove. • Supporto RTL Layout completo da destra a sinistra per le lingue RTL come arabo, persiano (farsi), ebraico e così via. Verdetto Slate è uno dei software open source più potenti per la generazione della documentazione e, in base alle discussioni con il mio mentore, il signor Chris Myers, utilizzerò Slate per la Parte 4 e per le altre parti verranno utilizzati GitHub e Markdown. Una visione più dettagliata della documentazione è descritta nelle sezioni di seguito. Struttura della documentazione proposta Ho creato una struttura per la guida utente di SynBioHub, che puoi trovare nella pagina 2. Questa struttura è accettata e già modificata dal signor Myers. Obiettivi del progetto 1. Ristrutturare la documentazione. 2. Aggiorna la documentazione in base alle versioni moderne di SynBioHub. 3. Rimuovi le informazioni obsolete. 4. Riscrivere la documentazione utente per renderla più comprensibile. 5. Includi nella documentazione una breve sezione sui prerequisiti per i nuovi collaboratori, in modo da migliorare la loro conoscenza di base dei concetti di biologia di base e dell'interfaccia di SynBioHub.