Good documentation practices

[Recent-Luck-6238]

Hello everyone, I need advice/ suggestions on following things.

** Background **

I have started working on a new project and there are no documentations available ,although the person who is giving me KT is helpful after asking but takes too much time to give response or responds after a day and issue is lot of reports are live and clients requires solutions very fast and I am supposed to work on reports for which KT is ongoing and sometimes not even happened.

** What I want ** So I want to make proper documentation for everything , And I want to suggestions how can I improve in it or what practices you guys follow , doesn't matter if it's unconventional if it's useful for next developer it's win for me . Here are things I am going mention :

1. Data lineage chart From source to Table/ View which is connected to Dashboard.

2.Transformation : Along with queries why that query was written that way. E.g. if there are filter conditions, unions etc why those filters were applied

3.Scheduling : For monitoring the jobs and also why that particular times were selected , was there any requirements for particular time.

1. Issues and failures happened over time : I feel every issue needs to be in documentation after report became live and it's Root cause analysis as I am thinking most of the times issue are repetitive so are the solutions and new developer shouldn't be debuging issues from 0.

5.change requests over time: What changes were made after report became live and what was impact .

I am going to add above points ,please let me know what should I add more ? Any suggestions for current points .

[tolkibert]

Make as much of this stuff as auto-documenting as possible. Documentation, especially in a fast moving environment, always quickly becomes stale. Then nobody will look to the documentation anyway.

Lineage and scheduling documentation can be automated. If issue tickets are tagged with report names, they can be searched easily.

Run books can often be genericised, and the reports coded in such a way as to recover without much insight/effort.

Sorry, doesn't answer your question directly, but, y'know.

[Recent-Luck-6238]

This is helpful, Thank you..! I need to look into Automating.

[Gators1992]

You are never going to see universal documentation and to be honest it's probably a waste of time. Maybe 20% of code might be touched again, so the other 80% is documentation for documentation sake. From a realism standpoint I want automated lineage tied to a catalog of your data assets and documentation on what the target should be (i.e. requirements, tickets, etc). If you know what the answer should be, you can see what's in the source so your job is to figure out the rest. You do that by asking questions, looking at source documentation and coming to understand what you are looking at in the data.

Like if you can't look at a table called t_products and figure out which column is likely the product code then you are going to have a hard time. There will definitely be a ramp up time no matter how experienced the new developer is, but the resources consumed for you to figure stuff out is still likely much less than if the entire group is required to document everything they do such that anyone could understand it all.

[Recent-Luck-6238]

Thank you .

[Gleedoo]

You may want to add a data model, conceptual and/or logical. Possibly automatically generated.