Re: Documentation Standard

Hi Yogi

My role is largely about platform architecture and automation now for other people to actually use.

On Thu, Nov 28, 2019 at 4:32 AM Tiwari, Yogesh <dmarc-noreply_at_freelists.org> wrote:

> Guys,
>
>
>
> I recently came about an interesting book, “Documenting Software
> Architecture”. It tells you how you can standardize documentation. I m
> curious, how ppl/orgs maintain their internal documentation for DBAs?
>
> There are all sorts of views on this, though…
>
>
>
> 1. Documentation platform like, confluence.
>
>
We use this for lots of our formal documentation. It's the main body of documentation. I have to say that it is difficult for people to find the exact items they are looking for (and tech people don't read docs *before*hand anyway). You do need a good predictable structure, a good indexing and tagging system and people to have bought into it.

>
> 1.
> 2. Word Docs
>
> We never use these. We do use powerpoint and videos/demos/recorded
meetings extensively to handover to teams that consume our stuff. .

>
> 1.
> 2. PyDoc type documentation
> 3. Documentation along with code, in markdown files etc.
>
> We use lots of code comments/documentation and certainly could use
PyDoc/JavaDoc, which we don't do currently. That said the quality and format of code comments/documentation is - let's just say https://xkcd.com/1296/ rings a bell. We do put effort into the README.md for each git code repo. We have *never *done this (man 5 sudoers). Please don't do this...

The *sudoers* file grammar will be described below in Extended Backus-Naur Form (EBNF). Don't despair if you are unfamiliar with EBNF; it is fairly simple, and the definitions below are annotated.

> What do you use, in your org, and if you can possibly explain, why please?
>
>
>
> Thanks,
>
> *Yogi *
>
> Disclaimer: The information transmitted is intended for the person or
> entity to which it is addressed and may contain confidential, privileged or
> copyrighted material or attorney work product. If you receive this in
> error, please contact the sender and delete the material from any system.
> Any unauthorised copying, disclosure or distribution of the material in
> this e-mail is strictly forbidden. Any comments or statements made are not
> necessarily those of Fidelity. All e-mails may be monitored or recorded.
>
>
>

-- 
Niall Litchfield
Oracle DBA
http://www.orawin.info

--
http://www.freelists.org/webpage/oracle-l