Re: Documentation Standard

  • From: niall.litchfield@xxxxxxxxx
  • To: dmarc-noreply@xxxxxxxxxxxxx
  • Date: Thu, 28 Nov 2019 17:36:18 +0000

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@xxxxxxxxxxxxx>
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

Other related posts: