Creating Documentation

Question

Creating Documentation

Steve Jones - SSC Editor

SSC Guru

Points: 736068
More actions
April 26, 2023 at 12:00 am

#4174197

Comments posted to this topic are about the item Creating Documentation

Viewing 12 posts - 1 through 11 (of 11 total)

You must be logged in to reply to this topic. Login to reply

Phil Parkin SSC Guru Points: 246942 More actions · Answer 1

If I do any significant development work, I document it myself in Confluence. This documentation remains internal, but for me has the following benefits:

I can send links to people within the company asking them to read it before any sort of meeting or demo takes place, thus (hopefully) speeding up everyone's understanding of what the work includes.
In six months' time when I need to make changes, I read my own documentation to refresh my mind as to what is going on.
It makes a nice change from bashing out code – I enjoy the variety.

The absence of evidence is not evidence of absence
- Martin Rees
The absence of consumable DDL, sample data and desired results is, however, evidence of the absence of my response
- Phil Parkin

Jo Pattyn SSC-Dedicated Points: 32341 More actions · Answer 2

We update short support documentation when we are on supportduty. Usually by another person than who wrote the program

It's necessary to support the number of applications, can't know it all and helps new teammembers how the application works.

Whilst it would be rather nice if the document is there when the program gets released

latkinson SSCommitted Points: 1673 More actions · Answer 3

I dislike writing documentation, I'm not very good at it. Its not that I'm a bad writer, I happen to believe that I write very well when I take the time.

But, time seems to always be at a premium for me, and documentation, any documentation, tends to suffer greatly. Its a task that I constantly need to work on improving and it keeps falling to the side in the rush to get the next project out of the queue.

One day, I will retire, or move on, and it sort of haunts me that so little of what I know and have done is still waiting to be documented for whoever ends up filling my position. Its a skill I need to work on, and until I get better, I will continue to dislike writing documentation.

Luther

HowardH.McIlwraith Grasshopper Points: 12 More actions · Answer 4

I think documentation should be part of the coding process, in part to assist oneself if you need to come back to it, but to help those who pick up the code down the line. More involved code should especially have documentation when either the logic is complex or when the business process within the logic may need some explanation. While there is an upfront cost to documentation, there are likely cost savings down the line for maintenance.

Rod at work SSC-Dedicated Points: 34003 More actions · Answer 5

I'm a developer and I don't like writing documentation. I've done it and I'm sure I'll do it in the future, but it isn't fun.

A lot of my career has been writing LOB apps, so internal customers. Even for them it's useful to write something so they know how to use the system. I like the way you described it, Steve, I tend to want to describe how a software system I've worked on is supposed to work. Guilty as charged.

At my previous job we also wrote software that was used by hundreds of people in the area. So, some documentation was necessary. Another thing we did is we had monthly meetings with those external users, to describe changes and get feedback. However, looking back at that experience I realize we really didn't get incremental feedback on how a system was being developed. The ideas of Agile and continuous feedback wasn't known to us. So, we would develop a new feature on our web app, show it to the external users at these meetings and that was it. If the users absolutely hated it, we'd make a change, but anything we produced was set in stone. I look back at this now with shame; we should have been more cooperative with the users to learn what they needed.

In my current position documentation is written, but developers, business analysts, PMs, etc. This is a much larger organization, so a lot of people have skin in the game. Unfortunately, even though Agile is something everyone has heard of and knows something about, there's a conscious effort not to practice it. I do try to emphasize the need to work together with the internal customers, but for the most part that hasn't worked out. At least I've tried.

Kindest Regards, Rod Connect with me on LinkedIn.

mfagan12 Default port Points: 1427 More actions · Answer 6

Writing is a form of communication and communication is one of the "soft skills" that are highly valued in the tech world. Having said that, as much as I loathe writing documentation, I do it and am good at it--based on the feedback from my colleagues. When I was in graduate school, my grad advisor insisted that I take a technical writing class and it's more come into play during the course of my career as I've written documentation for end users (like user manuals and acceptance test guides), other developers, and external vendors.

I tell my subordinates that they have to "know their audience" for both speaking and writing and to write professionally (one has a bad habit of using what I call "text speak" in emails and even message boxes that the end user sees) because they're junior programmers who often get too technical for non-technical people, which confuses and intimidates non-technical people and since we're in a small company, it's something that isn't desired. Sadly, despite the number of years they've worked, I'm still having to coach and correct them. . . 🙁

KerryH SSChasing Mays Points: 632 More actions · Answer 7

I think documentation starts in design. Pick meaningful and concise table / column / database object names. For instance, order number maybe too generic; is it a sales, purchase, shop, or another kind of order? And data types help to describe the content of a field. I document within my code basically adding comments to most pieces of code as to what it is doing and why, giving some background as to why that piece of code was written. I write code that will be supported by another teams, so code documentation helps. And it typically doesn't get lost somewhere else if it's with the code. This is not required by my company, but I want to 'leave a legacy' as I am nearing retirement.

I took an Agile course a couple years ago that gave one of the 4 pillars of Agile to be "Working Software Over Documentation", stating documentation is not as import as software. This concerned me a little. When is a developer not under a time crunch and will sacrifice documentation? You should understand before writing software, otherwise you don't know what you're writing; and to know what you're writing you do research / learning; why wouldn't you document that?

Greg Edwards-268690 SSC-Insane Points: 20680 More actions · Answer 8

We found ourselves documenting in business terms for consumers of the data, and having our technical documentation was useful. More work - certainly. This is what you asked for, here is how we did it. Did we miss something, or did you forget some details? And when people change on either end, they both have a good starting point.

Rod at work SSC-Dedicated Points: 34003 More actions · Answer 9

KerryH wrote:

I think documentation starts in design. Pick meaningful and concise table / column / database object names. For instance, order number maybe too generic; is it a sales, purchase, shop, or another kind of order? And data types help to describe the content of a field. I document within my code basically adding comments to most pieces of code as to what it is doing and why, giving some background as to why that piece of code was written. I write code that will be supported by another teams, so code documentation helps. And it typically doesn't get lost somewhere else if it's with the code. This is not required by my company, but I want to 'leave a legacy' as I am nearing retirement.
I took an Agile course a couple years ago that gave one of the 4 pillars of Agile to be "Working Software Over Documentation", stating documentation is not as import as software. This concerned me a little. When is a developer not under a time crunch and will sacrifice documentation? You should understand before writing software, otherwise you don't know what you're writing; and to know what you're writing you do research / learning; why wouldn't you document that?

I don't believe that Agile or DevOps discourages all writing of documentation. More they're trying to avoid the habit of Waterfall which prevented developers from touching a keyboard until everything was documented to the nth degree, with charts, graphs, Gantt charts, detailed project plans specifying how everyone involved had to be communicated with, etc. It could take several months to years before anyone could begin to code anything. By then the document was often too out of date to be of any use, but the document that's been generated must be followed as if it were the words of God.

Kindest Regards, Rod Connect with me on LinkedIn.

KerryH SSChasing Mays Points: 632 More actions · Answer 10

I work mainly on the DW side of the business, providing data for business data analysis. What we have found with the business is that with promotions, moves, and turnover there are many businesspeople who have a less than full understanding of their business processes. In our environment IT people help them acquire a deeper understanding because IT can dive into the code and figure out the business. This is an integral step in providing data lineage documentation for the business. To consume data mart data properly you need that understanding, otherwise different data analysts can produce different reporting results from the same data source.

We are building a wiki type documentation process so various parties in the business, both IT and business users, can suggest documentation for use by others.

In my experience company commitment to documentation is usually less than desirable. Years ago, we have a code promotion process that required documentation. Don't see that anymore.

David.Poole SSC Guru Points: 75992 More actions · Answer 11

I write for my future self and colleagues and see documentation as being part of my duties as a principal engineer. That said I do make it easier for myself by writing to be easily curated and published.

Think of Redgate SQLDoc. As long as you put meaningful business descriptions against database objects the tool will write your DB documentation for you.

For Python you have Sphinx to take your code and DocStrings and convert it to documentation. Java has JavaDoc. Various languages have various auto-documentation tools. Our CTO built an auto-documenter for Terraform code.

I understand that people find documentation a chore. A stitch in time saves nine. As your knowledge fades the task becomes harder, not easier.

I find it frustrating that people will argue about why they shouldn't do a task and sit in meetings opining vociferously for infinitely longer than it would actually take to do the task. If they do it, they pay lip service and do it with bad grace.

Documentation should be focussed on the reader. If a diagram makes it clear, use a diagram. Whatever communicates succinctly and effectively, use it.

I've seen so much money wasted replacing systems because the developers have moved on and no-one has anything other than the code itself to try and work out how everything works.

LinkedIn Profile