Software per gestire la documentazione

[paolo.giannelli]

Sto valutando quale software utilizzare per la documentazione interna di procedure e manuali operativi e mi sono imbattuto nell’interessante Wiki.js un software di tipo wiki.
La versione attuale (quella testata) di Wiki.js è la 2.5.283 uscita il 16 maggio 2022 e stanno già lavorando alla versione 3.0.
Il software è open source con licenza AGPL-v3.

Caratteristiche principali di Wiki.js

Wiki.js è un software wiki con caratteristiche interessanti:

• Gira su Node.js dalla versione 10.12.
• Wiki.js può utilizzare uno di questi database a scelta per contenere i suoi dati: MariaDB, PostgreSQL, MySQL, SQLite o MS-SQL Server.
• Ha l’integrazione con diversi motori di analitiche (tra i quali Google Analytics).
• Ha un suo sistema di autenticazione ed integra moltissimi sistemi esterni.
• Utilizza un editor di tipo markdown oppure HTML.
• Ha un sistema integrato di logging.
• Ha due motori di ricerca interni ed è interfacciato con diversi sistemi esterni (non con Google).
• Ha un suo sistema di backup.
• Ha una buona documentazione.
• Ha il supporto multilingua.
• Ha un sistema di profilazione per definire: amministratori, editor e semplici visualizzatori.
• Si può impostare la data in cui verrà reso pubblico un articolo.
• È possibile avere sezioni riservate della documentazione abilitate solo ad un gruppo di utenti.
• Ha una parametrizzazione completa delle funzionalità.

Ad una prima analisi questo software sembra fatto molto bene.
Per testarlo sul mio pc è bastato eseguire gli script Power Shell e si è installato in automatico come su di una macchina Linux.

Qualcuno lo conosce?
Voi cosa utilizzate per la vostra documentazione?

[sarcaz]

Ciao Paolo, noi lo utilizziamo da un po’ e ci stiamo sviluppando sopra la documentazione del nostro ERP. Devo dire che siamo soddisfatti, il prodotto è funzionale ed anche piacevole per l’utente finale.
In più, cosa da non sottovalutare supporta SSO con MFA

Prima usavamo DokuWiki ma è una soluzione ormai datata.

Ciao

[paolo.giannelli]

Aggiungo alcune considerazioni sui test che ho effettuato, così chi non lo conosce si può fare un’idea.

Aspetto generale.

Per il momento non ha una gestione dei temi grafici (è in fase di realizzazione) ma è possibile sovrascrivere il CSS in modo semplice. Nel nostro test abbiamo nascosto il box che contiene l’autore di un articolo e inserito velocemente il logo Instant Developer.

Sovrascrittura CSS

Indice argomenti pagina

Ogni pagina presenta l’indice degli argomenti in base hai titoli (h1, h2, h3, ecc.).

Motore di ricerca

La ricerca degli argomenti è possibile tramite motori esterni oppure sul database con ricerca full text che mi pare già funzioni bene.

Gestione e ricerca per tag

È possibile associare uno o più tag ad un articolo e poi eseguire ricerche per tag.

Navigazione sull’indice articoli

Ogni articolo ha la possibilità di essere nidificato in un percorso virtuale che ne identifica l’appartenenza ad una determinata libreria o insieme di articoli.

Menu principale personalizzato

È possibile avere oltre al menu di navigazione delle cartelle virtuali e argomenti anche un menu personalizzato che contiene delle voci fisse.

Gestione pagine

La gestione delle pagine (articoli) è possibile sia durante la navigazione degli articoli che da una pagina specifica:

Diversi tipi di editor

Sono presenti diverse modalità di editazione degli articoli: Markdown, Visual Editor (HTML) e raw HTML.

Markdown.

Visual editor.

Raw HTML.

Gestione commenti

È possibile commentare le pagine per gli utenti registrati.

Cronologia modifiche

Di ogni articolo è possibile visualizzare la cronologia delle modifiche e ripristinare una versione precedente a qualunque livello.

Inoltre posso creare branch di una versione, vedere le differenze con la precedente.

Aree private

È possibile creare delle aree private al solo utilizzo di alcuni gruppi e negando l’accesso agli altri utenti.

Web API

Sono presenti delle web api per interagire con i documenti e inserire o modificare pagine.

Lo standard utilizzato è quello di GraphQL ed è possibile interrogare il database e creare o modificare contenuti.
Per leggere dati in POST questo è un esempio di sintassi della query da mettere nel body della richiesta per ottenere la lista delle pagine:

query {
  pages {
    list {
       id
       title
       description
       path
    }
  }
}

Per inserire una nuova pagina questo il codice:

mutation Page {
  pages {
    create (content:"contenuto", description:"descrizione", editor: "code", isPublished: true, isPrivate: false, locale: "it", path:"/", tags: ["tag1", "tag2"], title:"titolo") {
      responseResult {
        succeeded,
        errorCode,
        slug,
        message
      },
      page {
        id,
        path,
        title
      }
    }
  }
}

[paolo.giannelli]

@sarcaz grazie della tua conferma della scelta.
Penso che la utilizzerò anche per sostituire la documentazione alle manovre operative che utilizza la scuola di canyoning dell’associazione di cui fa parte da vent’anni:
AIC Wiki realizzato con il software di MediaWiki.

Magari c’è anche una qualche utility per migrarne i contenuti.

[gaetano.mantovani]

Ciao, solo per info abbiamo iniziato a buttarci un occhiata anche noi per creare la documentazione del ERP/CRM che stiamo sviluppando con InDe Cloud.
Allo stato attuale l’ho installato su una macchina Linux hostata su Microsoft Azure (tenant aziendale). E al momento ho permesso l’accesso alla pagina wiki solo dai nostri IP aziendali. Ho forzato il redirect SSL (tramite Let’s Encrypt).
L’installazione fatta seguendo tutto quanto scritto qui: Install on Ubuntu 18.04 / 20.04 / 22.04 LTS | Wiki.js
con una nota, la parte “setup containers” va preceduta da un “sudo su” (almeno nel mio scenario) altrimenti non funziona dando l’errore permissions denied.

Condividerò con voi eventuali informazioni utili se ne avrò, ad esempio mi piacerebbe integrare GA4 e/o Azure Storage Account e se vedo qualcosa che può essere utile anche ad altri scriverò qui le mie considerazioni.

La creazione delle pagine l’ho delegata alla mia collega che riesce meglio in queste cose (sicuramente meglio di me ahah)
Ciao a tutti

[paolo.giannelli]

@gaetano.mantovani mi fa piacere che il mio sforzo serva a qualcuno e grazie delle eventuali info che arriveranno.