Are there comments standards for Technicians/Developers?

[rod.gallegos]

Hello, 

Beginning with the end in mind; it is in the end of an engagement with a customer that I hand over an export of all Jira stories from all sprints to a customer. Ideally, the customer uses the exported file (Excel) for training and to have some type of documentation of all work that has been completed. 

I am looking for some direction or resources for Techs/Developers to reference when it comes to making comments within Jira stories. There is a special difficultly in keeping comments brief and the tendency to over explain to a point of possible confusion is a constant temptation and mistake that is made. For example, if a story I am assigned to work states that an email template be configured to meet such and such criteria and should display specified colors and images, how should I best go about commenting my updates and configurations so as to keep my work updates concise and useful with the goal in mind, which I mentioned earlier.

Any help in this regard is welcome and I apologize if I am unclear in my request but am happy to answer questions. 

[Mark Segall · Accepted solution]

Hi @rod.gallegos and welcome to the community!

I think you're trying to solve for two cases in terms of providing content:

1. Issue detail - I always let (and encourage) verbosity in issue comments because it gives someone outside of the process a sense of how a decision may have came about. 
2. Solution architecture - Depending upon complexity of what I'm delivering, I will roll up tactical nature of the individual stories into the Epic description for smaller efforts and/or a Confluence space for more complex projects.

So to answer your question... I wouldn't constrain your developers from being verbose in the comments.  Make sure the stories are well formatted using the "As a _ I want to _ so that _" and include acceptance criteria.  Additionally, if there are more than a handful of acceptance criteria, explore breaking up the story into smaller pieces as the number of criteria is directly proportional to comment volume.

Hope this helps.

[rod.gallegos]

Thank you for your answer @Mark Segall and thank you also for helping me parse out my cases. Your explanation touches on some things I was sensing but couldn't exactly pin point. I am very glad I posted this question as you have helped clarify what was once cluttered in my mind.