Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione di Documenti Google.
Riepilogo progetto
- Organizzazione open source:
- Creative Commons
- Redattore tecnico:
- nimishnb
- Nome del progetto:
- Guida all'utilizzo del vocabolario
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Sinossi del progetto
Vocabulary ha un enorme potenziale per essere utilizzato come libreria di componenti dell'interfaccia utente principale per la creazione di siti web. Ciò che serve è una guida dettagliata, ma adatta anche ai non addetti ai lavori. Informazioni importanti per gli sviluppatori, come guide ai componenti, specifiche di utilizzo e modifiche di configurazione, costituiscono una parte essenziale di qualsiasi documentazione. Ciò non solo incoraggerà gli utenti esistenti a farsi un'idea di come il vocabolario continua a crescere e a raggiungere nuovi traguardi, ma promuoverà anche l'utilizzo del vocabolario in progetti relativamente più recenti. I risultati auspicati durante il mio lavoro di stagista non riguardavano solo la stesura di una guida senza fronzoli all'utilizzo dei componenti preesistenti, ma anche la progettazione e lo sviluppo di una home page (che porta a una documentazione integrata per ciascuno) per Vocabulary, Vue-Vocabulary e Fonts.
Progetto
Il problema: la documentazione è uno dei motivi principali che determinano il successo di una determinata libreria open source. La domanda principale che gli sviluppatori si pongono quando scelgono uno stack tecnologico adatto per creare le proprie applicazioni è: "La libreria è ben documentata? È ben tenuto? Ha un supporto sufficiente per l'utilizzo e gli errori?". Queste sono esattamente le domande che dovremmo porci quando affrontiamo l'idea di questo progetto. Dal punto di vista dell'ingegneria del software:
Analisi dei requisiti: è necessario disporre di una documentazione concisa e consolidata per le nostre esigenze. La mancanza di documentazione danneggia le prospettive future delle applicazioni open source ed è di gran lunga un componente essenziale e non trascurabile. Il link a queste documentazioni dovrebbe essere una home page accattivante, che catturi l'interesse delle persone in un istante. La documentazione deve essere ben organizzata, in modo da consentire un flusso continuo.
Specifiche: a seconda dei requisiti, è possibile decidere le specifiche. I contenuti della documentazione possono essere costituiti dai dati presenti nei siti web di Netlify di CC, oltre a qualche ispirazione da documentazioni ben note come semantic-ui, scikit-learn, numpy, bootstrap e così via. L'output di questa attività sarà la pagina di destinazione richiesta e le guide alla documentazione completa.
Alcuni problemi generali relativi a Vocabulary, Vue-Vocabulary e Fonts:
Manca la documentazione e, anche se è presente, alcune parti sono sparse nei siti web di Netlify. Ciò non impedisce a utenti, sviluppatori o collaboratori esterni di utilizzare la nostra libreria.
Per accedere a un determinato componente e copiare il codice corrispondente sono necessari ulteriori clic. Una semplice ricerca su Google di un termine come "Componente Tabs, vocabolario CC" non restituisce le informazioni desiderate. Un'opzione di ricerca nelle guide della documentazione migliorerebbe notevolmente la UX.
Una descrizione un po' più dettagliata dei componenti, che descriva i dettagli non evidenti.
Nessuna opzione di esecuzione in tempo reale. Un'esecuzione dal vivo è supportata da vari siti come JSFiddle, che consente agli sviluppatori di farsi un'idea del componente senza eseguire un'intera applicazione per vederlo funzionare.
La soluzione
Sono possibili più soluzioni. Tuttavia, ne illustrerò alcune qui e presenterò la mia soluzione finale nella parte conclusiva:
= Utilizzo di readthedocs readthedocs è una soluzione ben nota per scrivere la documentazione per le librerie open source. Si basa su Sphinx, lo strumento di documentazione Python.
Pro:
- Forma ampiamente accettata di generazione di documentazione, utilizzata da organizzazioni come Ethereum (Solidity).
- Documentazione strutturata in modo ottimale.
- Hosting statico senza costi.
Contro:
- Mancanza di controllo assoluto sullo stile.
= Utilizzo di Sphinx Potremmo utilizzare Sphinx anche per la parte di documentazione, in quanto offre ottime funzionalità per tutti i nostri scopi.
Pro:
- Lo strumento Python più popolare per la documentazione.
- Supporta anche le ricerche nella documentazione.
- Il CSS predefinito può essere sostituito con uno personalizzato; un certo controllo sull'HTML utilizzando i file .rst.
Contro:
- Richiede la programmazione in Python e nel formato di testo ristrutturato (.rst), che rappresenta una deviazione dai linguaggi di progetto suggeriti.
= Utilizzo dei temi Jekyll I temi Jekyll sono integrati nelle pagine di GitHub e sono disponibili modelli preesistenti che possono essere personalizzati in base alle nostre esigenze.
Pro:
- Temi di documentazione pronti all'uso per tutti gli scopi.
- Gli stili e i CSS predefiniti possono essere sostituiti con stili personalizzati, nonché controllo sull'HTML.
- Estrae il CSS di Primer predefinito per la creazione delle pagine.
- Integrazione semplice con le pagine GitHub.
Contro:
- Potrebbe non fornire la migliore struttura della documentazione.
=Utilizzo di GitHub Pages Le pagine GitHub standard per creare il nostro sito statico (HTML, CSS, JS).
Pro:
- Controllo completo su quasi tutto ciò che riguarda la questione.
- Massima flessibilità nella scelta di layout, colori e stili.
- Facile utilizzo dei componenti del vocabolario.
- Facile incorporamento di snippet di codice e link di esecuzione in tempo reale.
Contro:
- Potrebbe essere un approccio più lungo.
= Utilizzo di Haroopad In alternativa, puoi utilizzare questa soluzione Markdown.
Pro:
- Richiederebbe una programmazione minima e complicata.
- L'attenzione si concentrerà sulla scrittura perfetta della documentazione.
Contro:
- Mancanza di controllo sul CSS.
- Potrebbe o meno avere il miglior supporto della community.
- Potrebbe non supportare MDX.
= Utilizzo di MKDocs In questo modo, viene fornita un'altra soluzione alternativa per Markdown.
Pro:
- Richiede un minimo di codice complicato (di nuovo).
- Scrivere di più, scrivere meno codice.
Contro:
- Mancanza di controllo sul CSS.
- Potrebbe non avere il miglior supporto della community.
- Utilizza Python; potrebbe essere necessario creare un'istanza Amazon S3.
= Utilizzo di VueJS + StorybookJS Questo approccio è comunemente utilizzato in Vocabulary e nei suoi repository correlati.
Pro:
- Attenersi a tecnologie che funzionano perfettamente, in base alle esperienze di lavoro passate.
- Familiarità con il codice di base.
- Nessuna tecnologia competente in questo spazio.
Contro:
- Per gli stessi scopi potrebbero essere presenti anche opzioni più semplici.
In conclusione, mi piacerebbe pensare che l'approccio che prevede l'approccio VueJS+Storybook (HTML,CSS,JS) sembri il più adatto, dato che anch'io lo ammiro. Tuttavia, ciò significherebbe anche che non interromperemo del tutto lo sviluppo di questa applicazione. Inoltre, sarebbe abbastanza semplice utilizzare i componenti CC-Vocabulary. Tuttavia, per decidere la struttura della documentazione, dobbiamo assolutamente considerare il modo in cui i contenuti sono suddivisi tra le sottotitoli nella documentazione di ReadTheDocs. Il sito web dell'interfaccia utente semantica (che utilizza StoryBook) mi ha colpito perché ha un aspetto minimalista e consente di capire facilmente ciò che vogliono con pochi clic. Oltre a Semantic-UI, ho esaminato anche Material Design, Primer, Bootstrap, Carbon Design e così via da utilizzare come guide di stile dell'interfaccia utente e sistemi di progettazione per il mio lavoro. Per trovare ispirazione, possiamo anche consultare temi già pronti per la documentazione di Jekyll.