Stiamo sviluppando una serie di strumenti per il nostro uso interno (solo). Stiamo scrivendo la documentazione in parallelo con il progresso dello sviluppo.
È importante fornire diversi formati di documentazione? Per il momento generiamo la documentazione solo in HTML
Passare da "nessuna documentazione" a "documentazione in HTML" è un miglioramento enorme . Passare da "documentazione in HTML" a "documentazione in HTML e PDF" è un miglioramento aggiuntivo molto piccolo, ma può richiedere molto lavoro. Preferirei che spendessi quel lavoro per migliorare la documentazione HTML o aggiungere altra documentazione HTML.
Se qualcuno dice "Preferisco la documentazione in PDF anziché in HTML", la tua risposta dovrebbe essere "Bene, dura". Se qualcuno dice "XYZ non è ancora documentato", la risposta dovrebbe essere "Lo farò adesso". (Ovviamente un po 'esagerato).
L'importante è scegliere un formato di documentazione che sia facilmente gestibile e che possa essere utilizzato come fonte per tutti i formati che si desidera supportare in futuro (utilizzando una catena di strumenti del generatore).
Ci sono diverse opzioni a seconda del tipo di documentazione che hai in mente: se gli strumenti che stai per documentare sono in realtà funzioni di libreria con un'API, strumenti come Javadoc o Doxygen potrebbero essere adatti. Se, tuttavia, stai parlando di programmi con un'interfaccia utente e una documentazione per l'utente finale, strumenti come Asciidoc o Docbook potrebbero essere migliori. Ma qualunque cosa tu scelga, ciò che IMHO dovrebbe evitare come un inferno è mantenere la stessa documentazione due volte in due formati diversi.
Leggi altre domande sui tag documentation