How to get developers to document?

lahimakonem · 2016-04-27T19:11:41.000Z

You cant make him document anything if he doesnt want to. For most developers, comments are enough if they know what they are doing.

michaelmtallman · 2016-04-27T19:19:53.000Z

You’re lucky you even got one document, in all seriousness.

Like others have said, coding as you go is actually more than acceptable, since you’re dealing with the specifics of a block, whether it is a function, subroutine, interface, etc. Since he is getting things in on time, adding the additional “fully documented” document would certainly push that back. Perhaps, having someone sit with him who can is a technical writer to look over the code, then clarify things on an “as-needed” basis. Being a small shop, that might be difficult to pull off, but just a thought.

esimard · 2016-04-27T19:23:09.000Z

Carlton3412:

. I asked him to document a site he developed for a client interface he did in .NET and HTML with a SQL backend. The documentation was only one page with basic information about logins and links.

It is what I would have given you. Documents on how to use the end product through the frontend.

Carlton3412:

What I wanted was a complete document that would allow an outside developer to step in if we needed help.

That belongs in the code itself. Any outside documentation on the inner working of code is bound to be outdated very quickly. Now depending on the size of the project you may want to ask for some chart like flow, uml. But for small project, you may very well be better off with inside the code documentation. Always remember that documentation and charts need to be kept updated for them to be usefull and even safe to read. Any outdated one could cause way more damage then good. This is why the documentation needed to understand how a function works belong with that function’s code.

This does not say that dev 2 will update comment, but there is way more chance it will be done if I can do it at the same time as I change the code then if I have to update a separate documents, then make sure everyone that has that documents get the latest version.

Also an outside documentation of the inner working of a code opens the door to someone that does not know what he is doing to go and make changes because he “thinks” he understood the documentation.

It opens the door for a dangerous document to be leaked outside the organisation. If I know exactly how it is working (And good enough to start development), more chances I can hack it.

If you want to know either the comments in his code is good enough for another dev to pick up the work, give a section of code to another dev and ask him to tell you what it does.

You will find outside documentation of inner working on big project with many people working on it, sometimes even people from outside. But then you need a good structure to ensure that this documentation is kept up to date.

You will see this often with API’s documentation, out of date, or missing section, but in the code itself, more then never the proper documentations is in it.

Now if you really want outside documentation, I think what I would do is somehow get this documentation to write itself from the structure of the code and the comments inside. Then it would update itself. I think this already exists but could not point you in the right direction, as all my documentation is with my code.

shackleman · 2016-04-27T19:39:46.000Z

Well written code shouldn’t need any external documenting. A few comments here and there to explain oddities is usually enough. If you mix that with source control, proper versioning, and commit comments you should be good to go with out ever needing external code and your process will ensure your documentation will not get out of date.

esimard · 2016-04-27T19:44:37.000Z

Also, unless you start the project from the ground up, rarely do modification will require the coder to have an overall understanding of the inner working. This is usually the result of a bad design and too much coupling.

What will be important for coder #2 will be to know what the code is doing right now, and what it should be doing tomorrow. From there, the structure, file names, class and function name should be enough to pin point where the change should happen. From there, the comment should clarify the requirement of parameters needed for the function to perform, the general idea of how the function will do it, and the details of what it is going to spit out.

Noticed I said “general idea of how the function will do it”! As far as the details of how it does it: if you do not understand it from the code itself you should not be playing with it. Unless coder #1 had some very very bad habits, but even then, coder #2, should just bang his head a few times and fix it.

As you can see it is mostly a “find a piece of bread crumbs and follow the trail”.

I think the time would be better spent on ensure proper structure, naming practice, and good coding habits. This will help future dev way more then documentation ever will.

brycekatz · 2016-04-27T19:44:44.000Z

anthonystringer:

Have you tried asking for those details?

Indeed. Asking for “site documentation” is asking for something to get misunderstood somewhere along the line. You got what you asked for … just not what you wanted. Ask better questions next time.

bradleytemby · 2016-04-27T19:48:11.000Z

If he’s commenting in his code, I’d leave it be. Asking for full, comprehensive documentation from a developer is the same thing as expecting a plumber to document exactly how each pipe was cut, threaded, flared, joined, and fastened together with what material, how tight, and how hot (for soldered pipes) and write it all in a manual for the carpenter. This would be a complete waste of time for the plumber and would cost more in the end. Truth is, the carpenter should give no f**ks about all this mess because that’s not in the job description for that person to know. If the pipes break or leak due to a bad joint, another plumber will come along and see exactly where the problem occurred and how; that person does not need the carpenter to present a 42 page manual on the exact specs of the previous plumber’s work; they should just see the leaking water, shut off the valve, and take the appropriate measures to trace, diagnose, and fix.

Comments in the code, much as arrows and markings on pipes for “hot,” “cold,” “steam,” etc. are the developer’s way of documenting the inner workings, change versioning, break-fix effect, etc. of the program. If this person is doing this correctly, then any competent dev should be able to take one look at a block of code, read the comments, and know exactly what to do if there’s a problem. If you want, you can try to get this person to use Jira or something to track changes or bugfixes, but that’s as far as I would push it.

I have several years of experience as a project/systems engineer collaborating with many different and diverse development teams of varying experience and skill (some were incredibly talented and some that could freeze up a computer by writing code for Hello World). If there’s one thing you’ll never get out of developers, no matter how much they’re pushed or threatened, that is comprehensive documentation, because that’s not what they are trained to do. They can write up a basic how-to and excellent flow charts, but don’t expect them to produce much else.

TL;dr: Devs write programs, not narratives; they work with logic and workflows, not superlatives and comparatives, that’s not their job.

MI50 · 2016-04-27T19:55:44.000Z

Have you assigned him a project specifically stating (What I wanted was a complete document that would allow an outside developer to step in if we needed help. )

See what happens

esimard · 2016-04-27T19:56:42.000Z

 If there's one thing you'll never get out of developers, no matter how much they're pushed or
 threatened, that is comprehensive documentation ....

Most developers can tell you what any piece of code do, verbally that is, ask them to write it down and you will probably end up with the code itself on a paper. You have to remember that for a developer, reading and writing code is like reading and writing a book, it is not a foreign language, it is English and it makes sense.

esimard · 2016-04-27T19:58:24.000Z

MI32:

Have you assigned him a project specifically stating (What I wanted was a complete document that would allow an outside developer to step in if we needed help. )

See what happens

If I was assigned that project, I would comment the following: “If outside developer does not understand code itself with the help of comments, you don’t want him to touch it.” then close it as completed.

mrg3 · 2016-04-27T20:23:59.000Z

Use these words

“Your paycheck depends on your ability to convey to me in written form exactly what I need information wise so I can justify your job to the people upstairs. I would use a lot of detail and explain everything. That way I can prove to them they don’t need to consider outsourcing development because by keeping it in house we maintain full control and here is the documentation to prove it. The detailed documentation shows them how hard you are working down here. Might even help me justify a bump in pay down the road because they LOVE detailed documentation upstairs.”

saluki · 2016-04-27T20:42:07.000Z

The paycheck is a mighty tool…

tdg2 · 2016-04-27T23:00:33.000Z

Writing a lot of docos myself, I think what you’re asking for is an “As Built” doco. That is, rather than coding details, more like "is accessed via URL X, sitting on Server Y with IP xx.xx.xx.xxx, with OS Z version whatever. Changes approved by $Dept, hosted by $Us/$SomeoneElse, etc. & so forth. To quote Bryce Katz above - Ask better questions

Example: We had a web site for one of our Depts who then decided IT_BAU should take over the yearly payments, etc. It was a few years on & people had left & suddenly contracts needed to be renewed, certificates had expired, & no-one knew who was on first & what was on 2nd.

If Dev can’t do this then I suggest getting a doco expert (or someone who loves docos) to do this to standardize docos for future ref (can sit with dev & ask the right questions) so anyone further down the track can know what was done. There are templates available online …somewhere…

minithumbs · 2016-04-28T05:15:46.000Z

don’t pay them until they do - make it a deliverable

ianmacdonald3 · 2016-04-28T05:58:58.000Z

Change language.

If fluid_level > 5 then do pump_control_routine(true)

Needs no explanation. It is effectively self-documenting, saving the coder a lot of time writing comments.

$= fUncTiOn() {c=4;c<rt;ct–) new ObJeCt({yeUckyeUckyeUck})
}}}})))}}}}};}}){}

-Needs about ten pages.

Point of fact, you wonder where along the way we’ve ditched the principle that ‘spaghetti code’ is a bad idea.

100 IF X=5 THEN GOTO 200 seems lucid by comparison, after all.

Unfortunately in Web work we don’t have a lot of choice, it’s basically js or nothing. Although, we can still avoid the worst practices of writing unreadable code.

henriqued8139 · 2016-04-28T08:31:44.000Z

Instead of documenting, it’s better to have readable code. Because if your code changes, who can guarantee that the documentation will also be updated?

stephenkurtz · 2016-04-28T09:24:28.000Z

The code is the documentation. If he at the very least comments his code, there shouldn’t be any documentation needed by him for someone else to pick up where he left off. The documentation outside of the SDLC portion should be left up to the project manager to handle for UAT, change management, etc.

lancelotrussell · 2016-04-28T10:16:57.000Z

I have never done a project stopping every 2 seconds to document everything it is ridiculous!

brycekatz · 2016-04-28T10:50:11.000Z

MiniThumbs:

don’t pay them until they do - make it a deliverable

Labor laws be damned, right?

jshowa6666 · 2016-04-28T13:19:10.000Z

For those saying that code is the documentation, it isn’t. That’s horrible practice for many reasons. The comments are the documentation as well as the design diagrams associated with it. Having to re-read and understand code takes a lot more time than re-reading comments in the code or a design document.

For example, if someone asked you for a design or documentation on a house, you wouldn’t provide the house. You’d provide the blue prints which is a higher level of abstraction.

I think the real issue is what kind of documentation do you want. In your post, you start off with client documentation for an application as an example and then, at the very end, say what you really want which is developer level documentation. Now providing basic login and link information for client documentation is not adequate if the intent of the document is to show clients how to use the software.

However, providing developer documentation (i.e. where a developer can step in), comments is generally enough. Design documentation is better, but depends on project scale and isn’t needed a lot of the time.