RE: Documentation Standard
Date: Fri, 29 Nov 2019 05:20:58 +0000
Message-ID: <BMXPR01MB359101F628C2CBC7CB963E20C6460_at_BMXPR01MB3591.INDPRD01.PROD.OUTLOOK.COM>
Thanks, Niall.
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.
From: niall.litchfield_at_gmail.com <niall.litchfield_at_gmail.com>
Sent: 28 November 2019 23:06
To: dmarc-noreply_at_freelists.org
Cc: oracle-l_at_freelists.org; Tiwari, Yogesh <Yogesh.Tiwari_at_fidelity.co.in>
Subject: 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<mailto: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…
- 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 beforehand 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/<https://urldefense.proofpoint.com/v2/url?u=https-3A__xkcd.com_1296_&d=DwMFaQ&c=SsZxQMfaWJ1sSVfloc5FVGba8BA_qR4Jzdt8ol2oSPA&r=z73EKtGMkOyHMZwSjVYW8xqUyA1Kkf-CJ-c3rGZxafU&m=mNjGjsI-8YK_3kETBbuxvXex6bt-dPBf0Zo8x0AFBuk&s=YFGC_0PtKRUsQfPKJsuYP__Ld8zqhS-4C56zznYGDlI&e=> 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<https://urldefense.proofpoint.com/v2/url?u=http-3A__www.orawin.info&d=DwMFaQ&c=SsZxQMfaWJ1sSVfloc5FVGba8BA_qR4Jzdt8ol2oSPA&r=z73EKtGMkOyHMZwSjVYW8xqUyA1Kkf-CJ-c3rGZxafU&m=mNjGjsI-8YK_3kETBbuxvXex6bt-dPBf0Zo8x0AFBuk&s=9TnKf_S0DS4FKBTuA0SUsiy0P0b6LCfFTsZCH81f16k&e=>
--
http://www.freelists.org/webpage/oracle-l
Received on Fri Nov 29 2019 - 06:20:58 CET