1

So I was told from higher-ups that a software engineer that left the company didn't document his processes and he should have as part of his duties. My gut reaction was to say - "you don't get what you don't ask for", this is more a project management issue. The estimates given were to "develop a working piece of software", and there was never any discussion about documentation.

Is it fair to assume that each and every developer should be responsible for creating documentation even when it is not explicitly mentioned as a deliverable?

user1220
  • 6,219
  • 3
  • 35
  • 46
  • 2
    Code documentation or user documentation? Some believe in self-documenting code. –  Feb 03 '15 at 15:38
  • 1
    I suppose committing code to a repository, submitting regular status updates, and such other useless stuff wasn't explicitly mentioned as a deliverable either? Seriously dude, where did you study Computer Science? – Masked Man Feb 03 '15 at 15:42
  • I answered assuming user documentation. In-code documentation shouldn't be a requirement since business people shouldn't tell programmers how to do their job. – Telastyn Feb 03 '15 at 15:51
  • If something is not a deliverable, how can anyone ask for it? – user1220 Feb 03 '15 at 17:00
  • So for sure they said "didn't document his processes" Processes is vague. I would expect code at a minimum to have some inline documentation. If nothing more than a description of function, class, .... – paparazzo Feb 03 '15 at 17:42
  • Processes like "what to do when certificates expire", or "how to move system from acceptance to production" or "how to run an import script" – user1220 Feb 03 '15 at 17:57
  • If that is "processes" then I would say that is not a standard deliverables unless called out. If they meant all that by "working" then that is a stretch. – paparazzo Feb 03 '15 at 18:30
  • 3
    @user1220, the things you cite are essential to keeping the system running. The mandate to "make it work" extends past the first five minutes of deployment, and by not asking if it was documented, multiple people fell down on the job. Use this incident to differentiate yourself: encourage higher-ups to leave budget for documentation (or deployment automation), and show you are addressing something that was previously an issue. – abought Feb 03 '15 at 18:31
  • 1
    It may or may not be your responibility to write formal documentation. It is your responsibility to ask what documentation they expect and then deliver it. Some level of documentation is used in almost every shop and it is rarely specifically asked for as part of the requirements unless you have a legal requirement because it is a general policy not one specific to each task. In this manner it is like code review or the use of source control which are also rarely specified per task. You should be asking what the documentation policy is your first week on a job and then you should follow it. – HLGEM Feb 03 '15 at 18:46
  • 3
    I will point out that ALL of our time estimates include time to produce necessary documentation and yours should too once you know what is considered necessary. I will also point out that nothing will kill a good reputation with your peers faster than leaving a job and no one can figure out what your stuff does or where it is or even what state it was in. They will remember the pain point of trying to fugre out what you should have documented long after you leave and when they see your name in the future when you interview with their current employers too. – HLGEM Feb 03 '15 at 18:50
  • The biggest "clue" from the question is that you referred to the developer as a "Software Engineer". That implies some level of not only following good software development practices but also good "Engineering" practices. Part of being a good engineer is documenting what you have done, how you do it, how it can be repeated, what were the results etc...While it is company dependent, almost always if the title has "Engineer" in it then documentation and systematic application of processes should definitely be considered as an expectation. Coding is only a small part of software development. – Dunk Feb 05 '15 at 19:12
  • My rule of thumb is if I have to ask how to do something more than once then it needs to be documented. It doesn't need to always be extravagant, a simple "how-to" text file can suffice. These documents come in real handy for those tasks that only get done every year or two. – Dunk Feb 05 '15 at 19:24

3 Answers3

9

A software developers job is not simply to write software that works but to write software which works and is maintainable.

Different organisations and people may have different views on what maintainable means but if you are part of a company that considers maintainability to be highly documented, fully unit tested code then your job is to write software which works, is highly documented (to your companies required standard) and fully unit tested.
That's what they hired you for, not to develop code in your own personal way.

If specific processes are required to make your work transferable to others then it's within reason that a company should expect you to document them. Otherwise, how will they cope with you being getting sick, or hit by a bus? for example.

Community
  • 1
Ross Drew
  • 2,713
  • 19
  • 31
  • 2
    If it wasn't asked for, or wasn't described in the company processes or training, though, how are you meant to know? It's up to the company to set expectations. – Jon Story Feb 03 '15 at 15:57
  • @JonStory If he is hired as a college graduate, then I agree. Someone more senior is expected to know better. You certainly wouldn't like to hire a CEO who says he didn't present the company's financial info to the shareholders because nobody told him to do so! – Masked Man Feb 03 '15 at 16:31
  • I see your point but I'm not sure it equates. – Jon Story Feb 03 '15 at 16:33
  • I've worked in companies where colleagues have kept information to themselves as a way to make themselves more valuable to the company. It's wrong. If specific processes are required to make your work transferable to others then it's within reason that a company should expect you to document them. – Ross Drew Feb 03 '15 at 16:37
  • Given the choice between a working system and documentation, most people would choose the first and forget about the latter. You don't ask for it, you don't get it, as I see it. – user1220 Feb 03 '15 at 16:59
  • Documentation is one of those things I think that is an afterthought at best. I try to document my code, and I will product technical guides to my work for my clients - with information such as debugging, troubleshooting, how it works, screen shots, how to interact with it, and finally a link to the code itself and contact info. – Rob Feb 03 '15 at 17:35
  • @Rob - but do you see that as your professional obligation or are you fulfilling a deliverable request? – user1220 Feb 03 '15 at 17:57
  • Most people would choose the output of a working system. On the other hand most people would also choose to work on a well documented system than one that works. Developers need to stop being so selfish. – Ross Drew Feb 04 '15 at 11:53
  • Selfish? It isn't up to them. They are not the ones dictating what is or what isn't a deliverable. – user1220 Feb 04 '15 at 15:55
  • It's selfish in that developers are way to keen to get something working with no consideration for how maintainable or intuitive their code is. That's just trying to make it as easy as possible for yourself. – Ross Drew Feb 04 '15 at 16:27
  • Maintainable or intuitive has nothing to do with documentation. I can build an easy to maintain system with intuitive code without any supporting documentation. – user1220 Feb 04 '15 at 16:57
  • You can write a system that users, developers, testers and support can easily understand, use and maintain without having any documentation whatsoever? In that case you are probably the only developer I have met or heard of in my 10 year career who can do so. – Ross Drew Feb 04 '15 at 17:20
  • So is documentation important enough to be an explicit deliverable and as such be asked for and allocated proper time? – user1220 Feb 04 '15 at 19:02
  • It is your duty, I would say, to find out what level of documentation a company requires then allocate the time you need to complete it. – Ross Drew Feb 05 '15 at 09:20
4

The answer to your question is company specific. I would have told you to check with your management, except that your management already told you point-blank.

There are many forms of documentation - documentation through Test Driven Development (TDD), formal documentation, comments, documentation through code, etc. You have to nail down with your management the type of documentation they are looking for and the style of this documentation. you don't get away with documenting any way you want.

Vietnhi Phuvan
  • 72,342
  • 8
  • 133
  • 268
1

It depends.

If the software is being released as an API for other programmers to use (even internally), there should be some manner of documentation/user-guide provided. That might not be formal documentation. It might just be an email with some example code. But that sort of customer support is necessary since the code is the product in that case.

Otherwise, if the people involved (or the industry itself) are older, then the expectation of documentation is fair.

Before the advent of the agile development methodology, formal documentation was a key part of the process. More formal industries (medical, banking, government) or industries that move more slowly (manufacturing for example) still make use of documentation. Also, people who learned about software development back before agile might expect documentation to be par for the course.

But for almost everyone else, they should be familiar with modern software development practices that tend to eschew documentation. It is unreasonable to assume that the developer will produce documentation without prompting.

Though, as you say, it is pretty trivial to explicitly include that as a requirement. When in doubt, communicate.

Telastyn
  • 36,240
  • 9
  • 87
  • 127
  • Yes, communicate. Make it explicit, it doesn't take much. Don't take it as a given. – user1220 Feb 03 '15 at 17:04
  • Documenting "Code" and documenting "Processes" are 2 different topics. Sure, you know how to perform a ground up build of your system today, but 6 months from now when you've been working on a different project you won't even know where to begin (or worse yet your replacement on the old project won't know where to begin). And certainly you won't be able to reliably duplicate the process unless you've documented that process. You might come close, but far too often you'll forget about that one little configuration setting or driver to install. – Dunk Feb 05 '15 at 19:35