Documentazione eseguibile

Mi piace asciidoc , risp. asciidoctor , a scopo di documentazione. È molto meglio di MS Word e si integra meglio con il controllo del codice sorgente rispetto a strumenti come Confluence.

Inoltre, sono a conoscenza degli strumenti che consentono di scrivere parti eseguibili all'interno della documentazione di asciidoc. Ad esempio, il codice PlantUML può essere incluso nel documento ed eseguito per integrare l'immagine renderizzata nella documentazione. Più verso la mia domanda, qualcosa come JQAssistant ci consente di scrivere regole eseguibili come parte della documentazione. Questo tipo di programmazione letterale è davvero bello per documentare le regole insieme a quelle regole di esecuzione e aiuta molto a non ottenere documentazione obsoleta.

La mia domanda non è necessariamente limitata a asciidoc (tor), ma ispirata a quanto sopra. Se esiste una soluzione tramite asciidoc, sono piuttosto interessato a scoprirlo.

Quello che vorrei essere in grado di fare è scrivere documenti di processo aziendali in uno stile di programmazione che possa essere eseguito per supportare il processo documentato.

Penso che sia meglio spiegarlo con un esempio o due:

• Il processo documentato ci dice che quando si inizia un progetto, dobbiamo compilare il modulo X e posizionarlo nella cartella Y (o sotto controllo di versione, o qualsiasi altra cosa). Attualmente, questo significa che qualcuno legge un PDF, quindi va altrove per cercare il modulo X , lo copia nel suo spazio di lavoro, lo modifica e lo salva in una cartella appena creata Y . Mi piacerebbe essere in grado invece di eseguire direttamente la documentazione in modo tale che l'ultima forma X copia sia inserita nella cartella Y e forse anche un editor sia direttamente aperto.

• Il processo documentato spiega che una versione deve essere taggata e le risorse X , Y e Z devono essere inserite in una cartella di archiviazione F . Di nuovo, questo può essere fatto manualmente, o idealmente, direttamente eseguito da quella documentazione.

La mia domanda si riduce a due parti: è qualcosa di simile anche attualmente disponibile e, in caso affermativo, fino a che punto possiamo prenderlo?

Posso vedere diverse limitazioni problematiche, naturalmente. Ad esempio, la codifica automatica della versione sopra citata richiederebbe una sorta di input (numero di versione). Avresti inoltre bisogno di un modo per decidere quali parti di una documentazione più lunga eseguire, se ad esempio contiene entrambe le descrizioni di cui sopra.

L'obiettivo generale è realistico? Qualcuno ha esperienza con un tale approccio o anche le migliori pratiche? Come andresti a introdurre qualcosa di simile?