Documentation - writing style

Question

I am currently documenting our development process, and more importantly the reasons why we do it a particular way. I am planning to write in the style that I used during my (physics) degree, and which is common in many mathematics and physics textbooks, which is along the following lines:

"Therefore, we now see that X is Y, because of Z"

"We can state that F(x)..."

This style is very natural to me, but it has raised some discussion and I would like to know whether there is theoretical basis to the way I plan to write. The name of the style, if it has one, and/or a link to a Wikipedia page should be enough to silence the doubters!

Thanks in advance.

Answer 1

That sounds like technical writing as taught on most scientific or engineering courses. It tends to make those without an academic background uncomfortable, but I still think it's the only way to write clear, concise, accurate, unambiguous documentation.

Answer 2

I can only speak for myself, and that is I really hate reading something like that. You won't reach any non-technical person with that style, and you will likely be branded as a theoretician by many technical (non-science) people. Since this is about your development process, you want people to actually enjoy reading it, or they won't read it at all.

But then, that may be just me and may also depend on my different language background.

Just ask yourself why most books about programming are not written in that kind of language.

Answer 3

Although I don't seem to find a link to a particular writing style, I think your method can be effective. I think it really depends on the audience (ie. future / current developers that will work with the code) as to how effective it will be.

Not sure how well having functions in your comments will go over with other developers, however; just be sure we don't have to read your code to figure out what your comments are saying. :)

Answer 4

I think it is called 'academic style' or somesuch.

However, I strongly recommend against using it at work. There are many reasons for this opinion, but the most important one (to me) is that people expect to read things in a certain style. You should always try to meet your audiences expectations. If you don't, they will easily forget what you wrote, or not read it at all.

If you write a thesis, they will expect it in this style, so you should write it that way. If you write a documentation of your processes, people will expect it to be in the style they are used to for this sort of documents. Have a look at how process documentation is written in your company and take that as a guideline.

My own experience with process documentation is that in 99 % of all cases, flowcharts are far superior to descriptive text, no matter which style the text is in. If you want to add some explanation (why you are doing it that way), that part obviously needs to be in text, but choose a style that matches your process description graphs.

The academic style, IMO, is not suitable for this.

Answer 5

Thanks all for your comments and thoughts, I'll take them onboard when I get back to the office on Monday.

Answer 6

If you read books such as Martin's "Clean Code", one of the main arguments that he makes is that you do not actually have to write an explaining narrative for everything you do because that tends to become inconsistent.

If you can write code that explains itself (e.g., full variable names instead of letters) then that is better, and comments remain just for mentioning what algorithm or technique you will use.

Of course, if you are writing physics software for NASA, that may be a different situation and there may be a sense in conserving the style familiar to your audience.

Answer 7

I've written plenty of documentation that was directed towards an audience of engineers (specifications, processes, and SDK documentation). It's also important to consider readability.

Your audience may all have college degrees, but they will still be able to comprehend the documentation faster if it's more readable. For some of them, English may be their second language -- the academic style of writing could be practically incomprehensible. Readable documentation can also help new team members get up to speed.

Graphics such as flowcharts are very important, but some people are not visual thinkers and prefer words.