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?

Improve this question
12
  • 2
    Code documentation or user documentation? Some believe in self-documenting code.
    – user8365
    Feb 3, 2015 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 3, 2015 at 15:42
  • 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 3, 2015 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 3, 2015 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 3, 2015 at 18:50

3 Answers 3

Reset to default
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.

Improve this answer
14
  • 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 3, 2015 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 3, 2015 at 16:31
  • I see your point but I'm not sure it equates.
    – Jon Story
    Feb 3, 2015 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 3, 2015 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 3, 2015 at 16:59
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.

Improve this answer
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.

Improve this answer
2
  • Yes, communicate. Make it explicit, it doesn't take much. Don't take it as a given.
    – user1220
    Feb 3, 2015 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 5, 2015 at 19:35

Not the answer you're looking for? Browse other questions tagged .