Re: Documentation Standard

Hi Yogi,

when I'm documenting "stuff", database or otherwise, I use plain text files so that they can be version controlled.

The format is either Asciidoctor or ReStructured Text, mainly the former but older docs are in the latter.

I generate PDFs using the asciidoctor-pdf command, I don;t generate Word documents.

With my older stuff in ReStructured Text, I generate Word and PDF documents with PanDoc. I have a Word template that supplies most of the styles I need in that conversion, and another for the PDFs, which go via a LaTeX conversion internally to Pandoc.

I used to do my docs in Word, but I got fed up of it constantly messing up the formatting. Something as simple as adding a new bullet point to a bulleted list, for example, would use a different bullet, a different alignment and/or font. Nothing I did would fix it, other than repeated use of CTRL-Z to undo the changes. Nightmare.

I occasionally also use raw LaTeX for documentation - my eBook on Oracle 10046 Trace Files, for example, uses that.

I think that covers it.

Cheers,
Norm.

--

Norman Dunbar
Dunbar IT Consultants Ltd

Registered address:
27a Lidget Hill
Pudsey
West Yorkshire
United Kingdom
LS28 7LG

Company Number: 05132767
--

http://www.freelists.org/webpage/oracle-l Received on Thu Nov 28 2019 - 13:50:13 CET