Who should create documentation for software? In many companies, it’s the developers. In fact, in Redgate, often our developers are tasked with updating articles for products on our documentation site. We do have a streamlined process that has developers can submitting changes in some format (markdown? ) and an automation process that automatically updates the site as part of a release.
However, we also have marketing people who are in charge of external articles and communications. They ensure that our product learning and university content is updated. They work with technical people to produce, edit, and publish content. These could be developers, advocates such as Grant or Ryan, or even partners. Our Friends of Redgate also help with content.
Who should write and update documentation? Developers might best know how software changes, especially for new features. I know that developers also hate this chore, and I think they often don’t have the best perspective because the documentation should explain how I use things, not how I built them or just how I expect them to work. Developers sometimes just want to document how they expect the software to work.
At the same time, marketing or some other area might not be aware of changes, necessitating more handoffs from the development teams. That can be a bottleneck in a DevOps flow. Of course, some of this process could be automated, like sending release notes to marketing. However, there is also the need for someone technical to review changes, which can require more resources. It could also mean marketing people ask developers to review changes, taking up their time anyway. If developers are like me, then they might just want to handle it themselves than communicate changes and still have to review someone else’s writeup.
There probably isn’t a hard and fast rule. Not everyone communicate the same, or even that well. Writing is a skill, and while I might ensure all developers work on this skill, I might also try to lean more on those people that communicate well to ensure docs are updated for our clients.
If you are building internal software, perhaps you forgo documentation entirely. I could see developers having a meeting with either QA staff or perhaps a business person to teach them what is changing. Then this person gets tasked with training others on the software rather than ensuring any formal documentation exists. Tribal knowledge might be the best solution here.
If you’re a developer, would you want to control documentation or avoid it like the plague? Let me know today in the comments.
Steve Jones
Listen to the podcast at Libsyn, Stitcher, Spotify, or iTunes.
Voice of the DBA 
I am a document hardliner for 2 reasons, at some later point in time there will be a question about your code and you can bet some higher up will try and pass the blame to you for some change that you made at some higher-ups request.
Nothing that get’s change in any code I write is done with out documenting it and a version increase. Even if the change being made is to the documentation in the code and not teh actual code itself it still get’s a version update or increase because it was changed. Being both verbose and a hardliner about this it has saved my butt on more than one occasion specifically where my boss or someone higher up asked for a change that later proved to be wrong/bad. Without thoroughly documenting it I would have to rely on my memory and the person asking me about the change would have to trust me and my memory. With it being documented they have no way to “pass the buck” to me should some change I was asked to make be a bad one.
When documenting something I don’t simply detail what it does but I also include any thoughts about the why of teh change if I feel it’s appropriate. For example one time a change was made because a mistake made elsewhere revealed a bug and so in teh documentation of the change I included that piece of information.
I find too many developers especially from certain backgrounds, are VERY bad about documentation. I worked at a software vendor who provided accounting software and it was like trying to squeeze blood from a rock to get the devs to document if they were from a certain background and maybe it’s a culture thing. I was not a dev at the time but more of an advanced support tech who did custom reporting for clients and teh go-to SQL guy within all of the support department so I did not have an inside view of the developer group but I did work directly with a few and the few who had teh same background as me confirmed that they too had difficulty getting others to properly document their work. When developers do this they make it that much harder on the department that has to produce the documentation that goes to teh client which can lead to bad documentation.
As a dev/SQL guy yourself have you noticed that depending on teh developers background/culture in general they are either less willing to document or more willing? I’m not trying to being discriminatory about this just citing possible difference in cultures. This is not to say every dev of my same background does document, we have some lazy ones to, I’m speaking in general, overall. I do know for a fact that when I worked there (and this was 15 years ago so bear that in mind) if a dev was from a specific culture they for teh majority of the time had great difficulty with approaching some new problem. if the problem was documented with a known solution these guys were like teh Flash with getting it done but when something new came up they were stumped. There was a 60 minutes piece on Tv maybe 20 years ago about how a certain country was working hard to encourage it’s citizens to learn tech, mainly programming, so they could be a force in teh tech world. The piece included classroom footage and the way they were taught was not the way I was. Instead of teaching the language and how to use it these guy were shown problems and the solution using the language and they drilled it into them so they were like a ChatBot where as soon as you presented the problem they could provide the answer very quickly. This in my mind explained why these devs had problems when something new came along but were the best amongst us all when it was something known. I wonder if that method of teaching changed or if its continued. To be clear this is in general, we had some devs from that culture who were like software Einstein’s.
LikeLike
I have tended to be tough about docs in the past, though less so now if you look at the SQL Sat repo 😦
That has saved me as well, not only by documenting code, but documenting decisions in email and tickets.
As far as culture goes, I don’t think this is cultural in many ways. I think it is training and experience, and there are lots of people here in the US, as well as other cultures, that I run across who learned to solve this issue, not learned to solve this class of issues. They move too fast, and even the 5 minutes for a sanity check with a colleague is too much.
In many ways, what I see from ChatGPT is about what I expect from the average programmer, which is not great.
LikeLike