Welcome Guest ( Log In | Register )

Outline · [ Standard ] · Linear+

 Documentation

views
     
TSlife4
post Jul 31 2021, 07:59 PM, updated 3y ago

Getting Started
**
Junior Member
211 posts

Joined: Apr 2012
Do your company got documatation and how it is organazied and well versed?

Do you guy draw UML digram for every flow?

How you guy keep the document updated ?


do you guy do document 1st before do actual coding?




malleus
post Aug 1 2021, 08:19 PM

Look at all my stars!!
*******
Senior Member
2,096 posts

Joined: Dec 2011
QUOTE(life4 @ Jul 31 2021, 07:59 PM)
Do your company got documatation and how it is organazied and well versed?

Do you guy draw UML digram for every flow?

How you guy keep the document updated ?
do you guy do document 1st before do actual coding?
*
The main issue with trying to maintain extremely comprehensive documentation is that it's so hard to maintain and keep up to date at all times.

What we document on confluence (or similar products) is just the top level business requirements for each major release or development milestone. This covers the requirements from the end users, the details of what we're going to propose, top level architecture diagrams, basically things that's less likely to change. UX ppl will be involved at this stage as well.

Business Analysts will then discuss with the various tech leads for the different work streams on how to split the work to be done into smaller chunks, and prepare the relevant story cards in Jira. The tech leads will then fill in the details into each story card, and for each card after discussion with the developers who will be working on it, further details will be fill in. Code commits for every story card is tagged with the card number in the commit message, to make it easier to refer back to Jira card that it came from.

So it's pretty much top level stuff in confluence, then the in depth details in Jira. What that's worked on can be expected to change as work goes along, due to previously unknown edge cases being identified, or change of business process along the way. To cater for such, additional work cards will be created in Jira for tracking purposes, and if it's a change of requirement, the previous card will then be linked to the new one.

So from this, there's no one single location where a master documentation with all the full details is being kept in.

We also make use of a tool to autogenerate the DB schema documentation for us, everytime there's a change of DB schema, this is shared to other teams or parties as needed, if there's any other parties that may ingest the data that we generate.
bumpo
post Aug 2 2021, 11:42 AM

On my way
****
Junior Member
632 posts

Joined: Mar 2013


the thing about documentation is that it is not universal
from my experience, usually business cares a lot more about functional documentation and will expect it to be updated/reflect actual functionality.
but wont care too much for technical ones such as network/infra or method/coding level

usually technical documentation is the one that gets squeezed coz its almost never budgeted for properly sweat.gif
Grammar Police
post Aug 2 2021, 04:14 PM

Casual
***
Junior Member
332 posts

Joined: Mar 2016
no lol
TSlife4
post Aug 4 2021, 09:04 PM

Getting Started
**
Junior Member
211 posts

Joined: Apr 2012
QUOTE(malleus @ Aug 1 2021, 08:19 PM)
The main issue with trying to maintain extremely comprehensive documentation is that it's so hard to maintain and keep up to date at all times.

What we document on confluence (or similar products) is just the top level business requirements for each major release or development milestone. This covers the requirements from the end users, the details of what we're going to propose, top level architecture diagrams, basically things that's less likely to change. UX ppl will be involved at this stage as well.

Business Analysts will then discuss with the various tech leads for the different work streams on how to split the work to be done into smaller chunks, and prepare the relevant story cards in Jira. The tech leads will then fill in the details into each story card, and for each card after discussion with the developers who will be working on it, further details will be fill in. Code commits for every story card is tagged with the card number in the commit message, to make it easier to refer back to Jira card that it came from.

So it's pretty much top level stuff in confluence, then the in depth details in Jira. What that's worked on can be expected to change as work goes along, due to previously unknown edge cases being identified, or change of business process along the way. To cater for such, additional work cards will be created in Jira for tracking purposes, and if it's a change of requirement, the previous card will then be linked to the new one.

So from this, there's no one single location where a master documentation with all the full details is being kept in.

We also make use of a tool to autogenerate the DB schema documentation for us, everytime there's a change of DB schema, this is shared to other teams or parties as needed, if there's any other parties that may ingest the data that we generate.
*
now my company having like a wiki for us to do the documentation before each development . yea as i find like need to draw uml diagram for every single api flow are quite hard to maintain in long run if someone not going to update. I agree on more high level documentation that showing the overall business flow logic .

silverhawk
post Aug 5 2021, 01:18 AM

I'm Positively Lustrous
Group Icon
Elite
4,735 posts

Joined: Jan 2003


QUOTE(life4 @ Aug 4 2021, 09:04 PM)
now my company having like a wiki for us to do the documentation before each development . yea as i find like need to draw uml diagram for every single api flow are quite hard to maintain in long run if someone not going to update. I agree on more high level documentation that showing the overall business flow logic .
*
Sounds like more academic theory than practical reality.

Code and features move too fast to keep such documentation up to date. For APIs, its better to have the docs done via postman or something similar. Postman lets you share collections and write documentation for it, and since the collection is likely shared with the team for dev/debug purposes, keeping it up to date is relatively painless. Its much more useful documentation as well.
malleus
post Aug 5 2021, 10:22 AM

Look at all my stars!!
*******
Senior Member
2,096 posts

Joined: Dec 2011
QUOTE(life4 @ Aug 4 2021, 09:04 PM)
now my company having like a wiki for us to do the documentation before each development . yea as i find like need to draw uml diagram for every single api flow are quite hard to maintain in long run if someone not going to update. I agree on more high level documentation that showing the overall business flow logic .
*
won't it be easier to just do it in Swagger? this can be checked into the same repository too. and postman collections can be generated from swagger too
Alphaseti P
post Aug 5 2021, 12:17 PM

New Member
*
Probation
9 posts

Joined: May 2019
We use Structurizr and documentation first before coding.
ragk
post Aug 6 2021, 02:24 PM

BooBoo~
*******
Senior Member
2,265 posts

Joined: Apr 2009


My current company do a lot of documents after project is done in the wiki, wiki search is useful since it search the content as well, although u might found article of different version (outdate and updated) but atleast it help u to link up everything, which imo its helpful. It's only doable if ur company appreciate it, many china-man mindset company dun care all of this, they only wan feature to release as soon as possible.
And we add alot of comment in our code as well, being working in few companies but current company by far have the most complete documentation, although we still have some really, really old legacy code which have no document...

user posted image
user posted image

This post has been edited by ragk: Aug 6 2021, 02:25 PM

 

Change to:
| Lo-Fi Version
0.0219sec    0.44    5 queries    GZIP Disabled
Time is now: 28th March 2024 - 07:38 PM