Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- National Resource for Network Biology (NRNB)
- Technical writer:
- Prubhtej_9
- Nome progetto:
- Crea la documentazione utente per SynBioHub e sviluppa tutorial per casi d'uso specifici
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Abstract
La documentazione per gli utenti è progettata per aiutare gli utenti finali a utilizzare un prodotto o servizio. Una buona documentazione utente è molto importante perché fornisce agli utenti un mezzo per imparare a utilizzare un software, le sue funzioni, suggerimenti, trucchi e anche risolvere problemi comuni riscontrati durante l'utilizzo del software. Riduce inoltre i costi di assistenza ed è parte dell'identità aziendale del prodotto, ad esempio una buona documentazione per gli utenti è un segnale della qualità del prodotto e del team di sviluppatori. Senza una buona documentazione per l'utente, un utente potrebbe non sapere come svolgere le operazioni sopra menzionate in modo efficace ed efficiente. La documentazione per gli utenti può svolgere un ruolo fondamentale nel garantire il successo di un prodotto, perché un'ottima comunicazione è e sarà sempre al centro di qualsiasi attività o prodotto. Inoltre, un'ottima documentazione prende questa comunicazione e la inserisce in un framework gestibile a cui tutti possono accedere per il successo. SynBioHub è un repository di progettazione per la biologia sintetica. È disponibile sia come sito web pubblico che come software open source. SynBioHub utilizza il Synthetic Biology Open Language (SBOL), uno standard open source per la rappresentazione di progetti genetici, e consente anche di condividere parti di progettazione da file GenBank e FASTA. SynBioHub può essere utilizzato per pubblicare una libreria di parti sintetiche e progetti as a Service, per condividere progetti con i collaboratori e per archiviare progettazioni di sistemi biologici a livello locale. È possibile accedere ai dati in 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 che consente agli utenti di caricare nuovi dati biologici nel database, visualizzare le parti di DNA, eseguire query per accedere alle parti desiderate e scaricare SBOL, GenBank, FASTA, ecc.
Stato attuale della documentazione:
Attualmente, la documentazione dell'utente è disponibile all'indirizzo https://synbiohub.github.io/api-docs/#about-synbiohub ". Questa è solo la documentazione dell'API e non esiste la documentazione della GUI che può aiutare l'utente a navigare all'interno del repository di progettazione. Anche la documentazione dell'API richiede un po' di aggiornamento, con alcuni argomenti specifici come la risoluzione di alcuni peculiari problemi che un utente potrebbe riscontrare. L'organizzazione ha registrato alcuni video tutorial, come quello qui. Non esiste alcuna documentazione scritta per l'utente su SynBioHub che possa offrire una guida all'utente.
Perché la documentazione utente proposta rappresenta un miglioramento rispetto a quella attuale? Creerò la documentazione GUI da zero utilizzando github e markdown come suggerito dal tutor, il signor Chris Myers. La documentazione per gli utenti proposta sarà strutturata in modo da migliorare e garantire efficienza, coerenza e tranquillità per qualsiasi utente finale. Conterrà guide scritte e le immagini associate, oltre a istruzioni e spiegazioni su come utilizzare ciascuna funzionalità del simulatore open source SynBioHub. Durante le discussioni con il Sig. Myers , è stato inoltre deciso che la documentazione API sarà unita alla GUI e conterrà 6 sezioni, di cui la sesta sezione sarà facoltativa. Le sezioni sono menzionate 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 sull'uso di ciascuna funzionalità GUI b) Tutorial per casi d'uso comuni 4. Documentazione dell'API - Sezione Endpoint 5. Documentazione sui plug-in 6. Risoluzione dei problemi e riferimenti futuri.
Parte 1:
In questa sezione, agli utenti viene fornita un'introduzione dettagliata e vari tutorial relativi a SynBioHub.
Parte 2:
In questa sezione vengono illustrati i vari modi con cui l'utente può installare il software open source utilizzando vari metodi, vale a dire: a) Dall'immagine predefinita b) Dall'origine c) Configurazione NGINX
Parte 3:
Questa è la parte più importante della documentazione e richiederà la maggior parte del tempo. Qui, ogni singolo dettaglio verrà aggiunto nel contesto della GUI. Come accennato in precedenza, in questa sezione verranno affrontati principalmente due problemi, ad esempio istruzioni dettagliate su come utilizzare ciascuna funzionalità della GUI e alcuni tutorial per casi d'uso comuni.
Parte 4:
Come già detto, per generare la documentazione di questa parte verrà utilizzato slate. In questa sezione saranno inclusi i seguenti endpoint: 1. Endpoint utente 2. Cerca endpoint 3. Scaricare Endpoints 4. Scaricare Endpoints 5. Endpoint per l'invio 6. Endpoint delle autorizzazioni. 7. Modifica endpoint 8. Endpoint degli allegati 9. Endpoint di amministrazione
Parte 5:
In questa sezione verrà inclusa la documentazione relativa al plug-in, già presente nella precedente documentazione di SynBioHub. Questa sezione sarà suddivisa in due sezioni, ovvero la specifica e l'implementazione del plug-in. Parte 6: [Facoltativo] Questa sezione include un elenco molto comune degli errori riscontrati dagli utenti e contiene alcune istruzioni per la risoluzione dei problemi. In base alla discussione con il Sig. Myers, è stato deciso che questa sezione può essere unita alla sezione introduttiva, se non dovesse durare troppo. Analisi Io e il signor Myers abbiamo parlato di come aggiornare la documentazione esistente e di scriverne una nuova per la GUI. In queste poche conversazioni, abbiamo formulato un layout di base per la nuova documentazione, menzionata sopra, e abbiamo indicato una stima delle tempistiche a pagina 5 qui sotto. Per quanto riguarda la discussione, utilizzerò github e markdown per creare la documentazione per ogni sezione, ad eccezione della Parte 4 della documentazione in cui verrà utilizzato slate. Slate:- Slate ti aiuta a creare documentazione sulle API accattivante, intelligente e reattiva. Slate è uno strumento basato su Ruby che genera un sito statico di documentazione sulle API a tre riquadri di grande impatto visivo a partire da un insieme di file di markdown. È stato costruito dallo sviluppatore Robert Lord nel 2013, quando era uno stagista di 18 anni presso l'azienda di software di viaggi "Tripit". Ha convinto il suo capo a fargli utilizzare come open source il progetto e il resto è storia. Presenta le seguenti caratteristiche: • Design semplice e intuitivo. Con Slate, la descrizione dell'API si trova sul lato sinistro della documentazione e tutti gli esempi di codice sono disponibili sul lato destro. Ispirato ai documenti dell'API di Stripe e PayPal. Il formato slate è reattivo, quindi è perfetto per tablet, telefoni e persino nella versione stampata. • Tutto in un'unica pagina: sono finiti i tempi in cui i tuoi utenti dovevano cercare in un milione di pagine per trovare ciò che cercavano. Slate riunisce l'intera documentazione in un'unica pagina. Tuttavia, non abbiamo sacrificato la possibilità di creare link. Mentre scorri il dito, l'hash del browser viene aggiornato all'intestazione più vicina; in questo modo, il collegamento a un punto specifico della documentazione è sempre naturale e semplice. • Slate è solo Markdown: quando scrivi documenti con Slate, ti basta scrivere Markdown per semplificarne 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ù linguaggi: se la tua API ha associazioni in più linguaggi di programmazione, puoi inserire facilmente delle schede per passare da uno all'altro. Nel documento puoi distinguere linguaggi diversi specificando il nome del linguaggio 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 necessità di configurazione. • Sommario automatico con scorrimento fluido all'estrema sinistra della pagina. Mentre scorri, viene visualizzata la posizione corrente nel documento. È anche veloce. Stiamo usando Slate in TripIt per creare la documentazione per la nostra nuova API, in cui il nostro sommario ha oltre 180 voci. Abbiamo fatto in modo che le prestazioni rimangano eccellenti anche per 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 ti consente di usufruire dell'hosting senza costi per i tuoi documenti con le pagine GitHub, ma semplifica anche l'esecuzione di richieste di pull ai tuoi documenti da parte di altri sviluppatori se trovano errori di battitura o altri problemi. Ovviamente, se non desideri utilizzare GitHub, puoi anche ospitare i tuoi documenti altrove. • Supporto RTL Layout completo da destra a sinistra per lingue con scrittura da destra a sinistra come arabo, persiano (farsi), ebraico ecc. Verdict Slate è uno dei software open source più potenti per generare la documentazione e, in base alle discussioni con il mio mentore, il signor Chris Myers, utilizzerò slate per la Parte 4 e per altre parti verranno utilizzati github e markdown. Una visione più dettagliata della documentazione è trattata nelle sezioni seguenti. Struttura per la documentazione proposta Ho creato una struttura per la guida dell'utente di SynBioHub, che puoi trovare a pagina 2. Questa struttura è accettata ed è già stata modificata dal Sig. Myers . Obiettivi del progetto 1. Ristruttura la documentazione. 2. Aggiorna la documentazione affinché si adatti alle versioni moderne di SynBioHub. 3. Rimuovi le informazioni obsolete. 4. Riscrivi la documentazione per l'utente per renderla più comprensibile. 5. Includi una breve sezione dei prerequisiti alla documentazione per i nuovi collaboratori in modo da aumentare la loro comprensione di base dei concetti biologici di base e dell'interfaccia di SynBioHub.