Summary
As a part of a recent discussion about strategy on The C++ Source within the Editorial Panel, I mooted my taxonomy of documentation, and claimed to be good at some aspects, and not others. This having raised eyebrows, I am keen to learn more of the wider world experience ...
Advertisement
As far as I can tell, Documentation is classically seen as one of two things:
The stuff you write in big officially signed-off documents, pertaining to a piece of work performed for your client / employer. It is primarily aimed at system users and maintainers
The stuff you write in HTML/PDF form that accompanies your open-source software. It is primarily aimed at users.
To my mind, both of these kinds of things fall into the class of things that developers don't like to do. Obviously, the first one tends to be done more rigorously and professionally than the second in general, since more tends to ride on its being effected well. (Or, at least, more immediate and tangible things, anyway.)
In our discussions I suggested that documentation is actually a wider and more diverse thing, and comprises the following categorisations:
Client Documentation. This is the stuff you write about your work work, aimed at system users and system maintainers. It typically includes project specifications, design documentation (UML and whatnot), deployment guidelines, etc. etc. It also, importantly, includes the act of passing on information on a person-to-person basis, such as when walking developers on your team, or of your client, through the implementation, and assisting them in joining or taking over the (part of the) project.
Library Documentation. (This covers both open-source activities and libraries that you might build/enhance as part of your work for client/employer, on which I expound below.)
Pedagogical Publications. This is the stuff that we crazed few who actually mix real work with writing articles, columns and books spend too much of our time doing.
Being taxonomically obsessed - largely to relieve the headaches I get with my personal technological future shock - I suggested a further breakdown of the second main type of documentation, as follows:
"Written Documentation". This is the classic stuff, being written text (usually in HTML/PDF) and discussing, for each particular library/component/API/class the aims, restrictions, targets, example code snippets, etc.
Sample Programs. As often as not, people learn libraries from sample code, and good sample code can teach a lot and engage potential users in one's library. Bad sample code can have the opposite effect: I've recently learned that I've been guilty of this with at least one of my libraries, Open-RJ - see here and here. This caused me to expand the samples to include, for the C-API and the C++ and STL mappings, a cut-to-the-bone example, showing minimal simple use of the libraries, in addition to the existing full-featured program that shows the full range of behaviour.
Component Interfaces. The actual component interfaces are an extremely important part of the documentation: the code is the documentation. Bertrand Meyers makes the point that this applies to consistency across libraries just as it does to individual components within them. I'm doubtful that any developer would disagree with this notion, but maintaining such consistency is a significant task.
In the discussion, I volunteered that I'm probably adequate at 1 and 3 but, for open-source libraries, am pretty sketchy at 2.a and, despite (humbly ...) being reasonably good at 2.c, also decidedly ordinary at 2.b. Another Ed Panel member questioned whether anyone who purports (or at least attempts) to be a decent author of technical articles and books could do so if they're bad at documentation. My feeling is that they can, albeit the reason might be expediency/sloth rather than an inate disjunction of abilities. Naturally, that's based on my own rather up-and-down status in this regard, mixed with my arrogance in assuming that I could be good at 2.a if I decided to put in the appropriate effort; I may well be wrong.
The question I seek to promote discussion on is whether developers must indeed be good at all forms - except 3 - to be considered successful (or at least competent) as a professional engineer. I'm also very interested to hear about projects that have had good success despite being lacking in one or more facets of their documentation.
Thanks in advance
P.S. If anyone out there is feeling altruistic, or has a college project on apply semi-automated tools to documentation, or some such, the STLSoft documentation is in sore need of improvement. :-)
No, I would not expect software developers to be good at all forms of documentation. That would be because they are just people, and everyone has strengths and weaknesses. Some coders are good at writing some forms of code and not other forms. Some coders can even write poetry, in English and in COBOL ;-)
Our saving graces include that fact that we can learn new tricks - for better or worse, and that we don't really work in isolation unless we choose to.
Anyone can get some tutition to improve their documentation skills. The degree to which we improve depends on who we are, how much we want to learn, how much time we spend on learning, and how the tutition is delivered. So given that one has the time, there are many ways that we can get help with our documentation.
Failing that, or maybe even extending that, we can always ask for help. Our peers and colleagues may have skills that can be applied, if we ask nicely enough. And you may also have strengths that match their weaknesses, so a mutually beneficial exchange of sorts is usually possible.
In the end, there is no excuse for poor documentation of any form.
> I think rule number one with regard to documentation is to > use proper English. What do U think? Am I being 2 harsh? > ;-)
No, but you are ill-informed. Unfortunately, a proper English title exceeded the title restrictions on Artima blogs. That's the sole reason for my using SMS syntax.
Maybe I'm just being picky, but I think that being able to express yourself is a core skill for developers. Given a choice between two people who can code correctly, I'll take the one who can draw analogies, write fluidly, and talk comprehensibly about their designs.
So would I, but all you are saying is that given a choice between two people, you'd take the one with more skills. I'm sure you'd also agree to your statement if it was the other way around ...
Given a choice between two people who can draw analogies, write fluidly, and talk comprehensibly about their designs, I'll take the one who can code correctly.
Communication is a core skill required for developers. But some can do it better that others and in different forms. My point is just that even if one's communications skills are not the best at the moment, they can be improved given training and experience.
> So would I, but all you are saying is that given a choice > between two people, you'd take the one with more skills. > I'm sure you'd also agree to your statement if it was the > other way around ... > > Given a choice between two people who can draw > analogies, write fluidly, and talk comprehensibly about > their designs, I'll take the one who can code > correctly.
There's more to it (for me). If I were hiring for development, I'd actually weight communication and interpersonal skills higher than uber-geek prowess once we are above that 'can write correct code' stage. It's nice when you can have both but without communication skills, there are just too many limitations.
> Communication is a core skill required for developers. But > some can do it better that others and in different forms. > My point is just that even if one's communications skills > are not the best at the moment, they can be > improved given training and experience.
> > So would I, but all you are saying is that given a > choice > > between two people, you'd take the one with more > skills. > > I'm sure you'd also agree to your statement if it was > the > > other way around ... > > > > Given a choice between two people who can draw > > analogies, write fluidly, and talk comprehensibly about > > their designs, I'll take the one who can code > > correctly. > > There's more to it (for me). If I were hiring for > development, I'd actually weight communication and > interpersonal skills higher than uber-geek prowess once we > are above that 'can write correct code' stage.
So would I, because there's more to a successful working environment/team to technical prowess. I don't many would argue with that.
But we're getting off the point of the post. My question is whether it's necessary for software engineers to be good at all facets of documentation, or reasonable for people to have that expectation. In my experience, few are, and yet this does not prevent projects being successfully completed and maintained.
> But we're getting off the point of the post. My question > is whether it's necessary for software engineers to be > good at all facets of documentation, or reasonable for > people to have that expectation. In my experience, few > are, and yet this does not prevent projects being > successfully completed and maintained.
I know that, personally, I tend to get better at what I like to do and it looks that way when I look at other people too.
I think that the problem with project documentation is not ability as much as motivation. Some forms of documentation have you essentially rearticulate things that you've articulated in the code, so it's a bit of a chore, and if enjoy coding more, you really have to stretch for that happy/satisfied 'did a good job' feeling when you document.
If we regard documentation as a form of recorded communication, then so long as developers are able to communicate to somebody who can document, then there is no need for every developer to be proficient in all facets of documentation.
> If we regard documentation as a form of recorded > communication, then so long as developers are able to > communicate to somebody who can document, then > there is no need for every developer to be proficient in > all facets of documentation.
Yes, that's what I feel might have some merit. (And help me out of what seems like the failed syllogism of skill-ubiquity versus unemployability.)
> > But we're getting off the point of the post. My > question > > is whether it's necessary for software engineers to be > > good at all facets of documentation, or reasonable for > > people to have that expectation. In my experience, few > > are, and yet this does not prevent projects being > > successfully completed and maintained. > > I know that, personally, I tend to get better at what I > like to do and it looks that way when I look at other > people too. > > I think that the problem with project documentation is not > ability as much as motivation. Some forms of > documentation have you essentially rearticulate things > that you've articulated in the code, so it's a bit of a > chore, and if enjoy coding more, you really have to > stretch for that happy/satisfied 'did a good job' feeling > when you document.
Yes, in practice I think that probably accounts for a great deal of the problem.
However, I also think that being an effective documenter also requires an ability to quickly and accurately and reliably put oneself into a position of not knowing all of what one knows, and that's a skill I haven't seen many humans demonstrate particularly well, nor does it seem something that should necessarily accompany skill in the doing.
A good developer is aimed to create a good quality software. A good technical writer accompanied with a developer is able to create a documentation which just shine.
I think that there is a great quality to developers that like writing other things that code. Not because that means that they will write documentation (even though it might) but because eloquence is, I think, a very powerful skill for a developer. Programming strong relations with linguistics. Developing algorithms and optimizing code might be more related to math and logic but designing the structure of a system is very much about naming functions, types and other entities, determining which relationships exist. That being said, writing good documentation also requires an ability to put yourself into the place of another - being able to picture the situation of another programmer trying to understand your code. Doxygen is very popular and with good reason - it is fabulous - but the documentation that is generated is rarely useful as is. This kind of documentation assumes that you already know which classes and functions you are going to use and that you are just trying to find out what the parameters are. Well if I know which class to use, Intellisense will quite often be more than enough for me. What I need is an introduction to the way you solve problems with the given library. And that can not be auto generated..
> No, but you are ill-informed. Unfortunately, a proper > English title exceeded the title restrictions on Artima > blogs. That's the sole reason for my using SMS syntax.
Brevity is the soul of wit. Learn to make every word count.
Flat View: This topic has 15 replies
on 2 pages
[
12
|
»
]
Previous Topic
