Nuovo plugin di documentazione in sviluppo

Annunci
,
1

Abbiamo recentemente reso disponibile il nostro nuovo plugin di documentazione per test e feedback. Questo plugin è progettato per migliorare la navigazione e l’accessibilità della documentazione ospitata su Discourse, offrendo un’esperienza più accessibile e user-friendly per tutti gli utenti. Nota che questo plugin è ancora in fase di sviluppo.

Lo sviluppo di questo plugin deriva dal nostro impegno continuo per migliorare la documentazione, che è già stato migliorato da una nuova barra laterale. Il lavoro sulla barra laterale ha posto le basi per un’esperienza di documentazione notevolmente migliorata, e il nuovo plugin si basa incrementalmente su tale lavoro.

:boom: Il nuovo plugin in azione

Il plugin è attualmente attivo e alimenta la documentazione sulla nostra documentazione ufficiale di Discourse. Ti invitiamo a esplorare le sue funzionalità e a condividere le tue esperienze con noi. Il tuo feedback è prezioso per aiutarci a perfezionare e migliorare il plugin.

Le funzionalità principali incluse nel nuovo plugin sono:

  • Impostazioni per definire quali categorie vengono utilizzate per la documentazione
  • Una nuova barra laterale della documentazione popolata da argomenti indice all’interno di ciascuna categoria
  • Due nuovi report per aiutare a mantenere l’integrità e l’accuratezza degli argomenti indice

Con altre funzionalità in fase di sviluppo mentre miglioriamo continuamente quelle disponibili.

Il nuovo plugin è disponibile per il download e l’installazione oggi stesso: Discourse Doc Categories

:electric_plug: Transizione dal plugin Discourse Docs

Mentre innoviamo e andiamo avanti, ritireremo il nostro vecchio plugin Discourse Docs. Puoi stare certo, tuttavia, che continueremo a supportarlo fino a quando il nuovo plugin non sarà completamente pronto per un rilascio diffuso. Abbiamo anche assicurato che il nuovo plugin reindirizzerà gli URL dal vecchio plugin, quindi il passaggio non comporterà collegamenti interrotti.

Si prega di notare che il nuovo plugin è ancora nelle sue fasi sperimentali. Sebbene miriamo a fornire un’esperienza senza interruzioni, potrebbero esserci alcune aree che richiedono ulteriori miglioramenti. Il tuo feedback costruttivo sarà cruciale per il suo successo.

:speaking_head: Facci sapere cosa ne pensi

Apprezzeremmo i tuoi pensieri, esperienze e feedback. Sentiti libero di condividere le tue esperienze e qualsiasi intuizione che raccogli utilizzando il nuovo plugin di documentazione, navigando attraverso la documentazione su Meta o installando il plugin sul tuo sito.

Il nostro obiettivo è plasmare una migliore esperienza di documentazione per l’intera community di Discourse, quindi tutto il feedback è benvenuto!

Dettagli completi del plugin disponibili qui:

13 Mi Piace
2

Qualcuno deve aggiornare il readme. E forse aggiornare le regole di lint per evitare che ciò accada, sebbene ci sia un problema dell’uovo/gallina.

Sembra che potrebbe essere ottimo anche per utilizzare Discourse come LMS. Per questo sarebbe utile poter scegliere quale categoria fosse una categoria di documentazione, sebbene ci sia una buona probabilità che l’uso dei permessi per dare agli utenti l’accesso a determinate categorie sia sufficiente affinché funzioni semplicemente.

8 Mi Piace
3

Ottima osservazione sull’URL: ho appena inviato una PR per aggiungerlo.

Sembra un caso d’uso interessante per questo, e posso capire come funzionerebbe abbastanza bene!

6 Mi Piace
4

Questo è un miglioramento fantastico rispetto al plugin originale Docs/knowledge base. Finora sembra molto facile da usare.

Testare su Meta è sicuramente un grande vantaggio poiché le categorie di documentazione qui potevano essere difficili da trovare in precedenza.

5 Mi Piace
5

Oso chiedere una stima dei tempi? Cioè, quando questo plugin sarà considerato meno sperimentale e più in una fase beta, o forse addirittura di early release candidate? So quanto sia difficile prevedere il futuro, quindi sarò felice di ricevere qualsiasi stima approssimativa, per quanto imprecisa possa essere. :wink:

Attualmente sto esplorando Discourse come strumento sul lavoro, proprio perché sembra in grado di offrire un buon mix di discussioni comunitarie e uno spazio condiviso per la documentazione. Dove è facile scrivere documentazione come postare un commento su un argomento.

Quindi, la funzionalità del topic wiki di per sé è ovviamente ottima, è un ottimo inizio. Questo plugin, però, aggiunge coesione al contenuto degli argomenti, che credo sia essenziale per l’esperienza utente della documentazione.

La categoria Documentazione su meta.discourse.org ora sembra un vero e proprio sito di documentazione strutturato, piuttosto che semplici argomenti casuali del forum che condividono una categoria e descrivono come funziona Discourse.

Quindi, continuate così. Grazie!

1 Mi Piace
7

Mi piace moltissimo! Documentazione e Discussioni si integrano molto bene.

Avete in programma di abilitare l’indicizzazione dei tag oltre alle categorie?

8

Penso che la fase in cui ci troviamo ora sia “la bellezza (o la sua assenza) è negli occhi di chi guarda”

È sperimentale nel senso che ci sono problemi di UX noti, in particolare per coloro che sono responsabili della manutenzione della documentazione e soprattutto degli indici, ma è completamente sicuro da usare in produzione.

Tutto ciò significa che apprezzeremmo molto il tuo feedback se lo provassi e lo mettessi alla prova tu stesso.

Non abbiamo alcuna ETA al momento per migliorare i problemi di UX noti con la manutenzione degli indici, ma il feedback delle persone che lo utilizzano potrebbe aiutare a guidare la direzione.

No, non è qualcosa che è emerso finora. Puoi condividere un po’ di più su cosa stai pensando o perché questo sarebbe utile per te?

4 Mi Piace
9

Riguardo a questo: se ti trovi in una categoria di documenti e chiudi una finestra di chat non a schermo intero, anche la navigazione del documento viene “chiusa” e viene nuovamente visualizzata la barra di navigazione normale. Mentre riproduco su meta, ho anche notato che facendo clic sulla bolla di chat (in alto a destra nell’intestazione) si chiude anche la navigazione del documento. Spero che questo aiuti!

3 Mi Piace
11

Grazie per la segnalazione: sono in grado di riprodurla, quindi l’ho registrata e la includeremo nel prossimo lavoro di sviluppo qui.

3 Mi Piace
13

Questo mi ricorda una cosa di Discourse come progetto, che non è proprio l’ideale per me come utente. Il fatto che il progetto non utilizzi un vero e proprio issue tracker pubblico per bug e pianificazione.

Ad esempio, quando leggo la risposta di Hugh, il mio project manager interno solleva immediatamente la domanda: dove, dove è stato registrato?. Lo so, il mio PM interno è una piccola creatura ficcanaso, non è vero? :slight_smile:

Suppongo che l’utilizzo di meta.discourse.org come issue tracker dia al progetto un’opportunità di “dogfooding” di Discourse. E tutti gli altri issue tracker hanno i loro difetti, quindi è un problema doverne scegliere uno. Ma per me Discourse - pur essendo eccellente come forum per domande e discussioni - è molto carente come issue tracker. A tal fine mancano una categorizzazione efficace, informazioni sulle versioni interessate e target, numeri di issue, prioritizzazione, mezzi efficaci per filtrare le issue per stato, età, priorità, prodotto o componenti, e un buon modo per presentare una roadmap per una funzionalità o per il prodotto nel suo complesso, tra le altre cose.

Bene, vado fuori tema. E non ho ancora contribuito con una singola riga di codice, segnalazione di bug o richiesta di funzionalità, quindi chi sono io per lamentarmi. :wink:

Quindi, ancora una volta, grazie a tutti per la grandezza di Discourse. E scusate il semi-sfogo.

E tornando all’argomento, è fantastico sapere che le Categorie di Documentazione di Discourse, pur non essendo ancora rifinite, sono considerate architettonicamente stabili. Verificherò se riesco a installarle sulla mia istanza Discourse ospitata e, in tal caso, proverò a tornare con un feedback. Grazie!

6 Mi Piace
14

Ho dimenticato di rispondere qui. Grazie per il tuo follow-up.

Capisco che #wiki potrebbe rientrare in diverse categorie come community support dev, ed è meglio mostrare i dati in base agli interessi degli utenti sugli argomenti.

Nel frattempo, mostrare quelle wiki organizzate nella documentazione (link nella barra laterale della wiki) sembra fantastico.

1 Mi Piace
15

Usiamo Discourse come issue tracker. Meglio dire – cerco di costringere il mio team a usare Discourse come issue tracker :slight_smile: E un wiki, e un forum, e una documentazione… Sospetto che il team CDCK abbia un altro sito Discourse “segreto” dove traccia le proprie cose internamente, usando alcuni plugin interessanti, che nessuno ha…

Non importa quanto sia buono l’issue tracker qui, la community non può essere paragonata a nient’altro che conosco. Alla fine sono le persone che sviluppano il software, non la tecnologia dietro di esso. E sono fantastiche! :metal:

E mi piace molto il plugin di documentazione. :heart:

Ora, con tutte le mie lodi, sarebbe possibile approvare il mio PR? :smiley:

5 Mi Piace
16

Hai visto la risposta di Gerhard su quel PR?

3 Mi Piace
17

Abbiamo un altro sito che usiamo internamente ed è proprio così che tracciamo gran parte del nostro lavoro. Ma non lo facciamo con plug-in segreti.

Principalmente, usiamo convenzioni, come una categoria per “todo” e un set standard di alcuni tag per una sorta di prioritizzazione ora/prossimo/dopo, insieme al plug-in di assegnazione per chiarire la proprietà.

Ciò consente anche al componente del tema kanban di funzionare, ma non tutti utilizzano quella visualizzazione.

È piuttosto fluido, non un issue tracker molto opinabile, ma funziona bene per noi.

Potrei condividere maggiori dettagli a volte…

6 Mi Piace
18

No! Colpa mia. Risolto. Grazie per l’avviso.

3 Mi Piace