3 Replies - 1173 Views - Last Post: 26 March 2014 - 02:20 AM

#1 Amruta2799  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 4
  • Joined: 16-March 14

What type of developer documents can actually help developers?

Posted 16 March 2014 - 11:32 PM

Hi All,

I am a Technical Writer.. but I don't write user documentation, I write developer documentation. I just started working at a new job, where I have to start developer documentation from scratch. I would really love your inputs as to what type of documents will make life easier for developers?

I work at a startup, where most people know each other, so they can just walk up to the developers and ask questions. So documentation wasn't required before. But now they are expanding the company, so they need documentation. Hope this clarifies the scenario.

Is This A Good Question/Topic? 0
  • +

Replies To: What type of developer documents can actually help developers?

#2 Skydiver  Icon User is offline

  • Code herder
  • member icon

Reputation: 3616
  • View blog
  • Posts: 11,268
  • Joined: 05-May 12

Re: What type of developer documents can actually help developers?

Posted 17 March 2014 - 06:27 AM

To me, the most useful documentation are:
- specific method level documentation so that I know how to call somebody else's code without having to dig too deeply into their source code. So that includes not only the methods of each class, but also the pre-conditions required by the method, and post-conditions as the result of calling that method.
- general organization level documentation that tells me where to find what I code I need in case I do need to dig into somebody else's source code.
- general "how do I build and test" somebody else's source code. In other words, what environment do I need, and how do I verify that I didn't break anything?
- general "how do I check in code" somebody else's source code. What "ceremonies" do I need to go through to check in a fix for old code or to put in new code? A code review? A design review? Just check it in and see if somebody screams?

Also, in general, I prefer to look at UML diagrams instead of reading text.
Was This Post Helpful? 3
  • +
  • -

#3 jon.kiparsky  Icon User is online

  • Pancakes!
  • member icon


Reputation: 7874
  • View blog
  • Posts: 13,356
  • Joined: 19-March 11

Re: What type of developer documents can actually help developers?

Posted 23 March 2014 - 09:06 PM

Not to discourage you, but I just left tech writing for programming because I found that there's very little actual interest in developer-facing documentation. There's a lot of expressed interest, but it's always something that people would love to have, and something they wish they had, when they find they need it - but it's never on the list of things that they actually want to make. So for me, tech writing was a very frustrating experience a lot of the time. On the other hand, I've got a lot of mileage in interviews by pointing out that, as an experience technical writer, I'm capable of helping internal documentation happen, if that's ever needed.
And people love that because they feel like they're paying just enough attention to the need for documentation by agreeing that that sounds nice - so far, people don't really ask me to devote any actual time to documentation, though.

That being said, I'd suggest that what people most need is the first-week material. That is, the stuff that a new developer most wants to know in the first week to first month on the job. What exactly that's going to be is going to depend on the local situation, but if you follow a new developer around and talk to them as they learn their way around, you'll find that there are things that they wish they'd been able to look up. You can then write those things down and organize them.
Some things that fall into this category are also useful to have on a longer-term basis. One example of this is infrastructure. Hopefully the systems guys have this covered, but often they don't, and it's often useful to know how all the pieces fit together - meaning both actual systems like servers and such and virtual systems, like different databases and code packages. This is the overview question: how does all of this stuff fit together? What's going on here?
In the same place, you'd like to make notes of any relevant details - who owns this? Who maintains it? What software is on it? What touches it? What dies if this dies? That sort of thing.
Things like coding standards, commit procedures, and the rest, would also fit neatly under "first-week" stuff.

One interesting area that I fell into as a documentation guy with a head for code was writing QA tests. These weren't the full-bore test suites, we had a QA department for those, but we wanted to have a few internal test suites that we could use as sanity checks. There was a "smoke test" suite, to check for the most basic signs of life in the system. Since we had a pretty complex web app to deal with, involving a bunch of databases and connectors and what-not, this was handy for eliminating system failures as causes of problems. Then there was a UI test - we used those to test whether core UI code had gotten borked by some change. This was handy for keeping the developers honest, and for preventing changes from getting established between QA cycles. And so forth. The interesting thing about this is that these tests really are documentation, in that they define the expected performance of the system. The UI should work like so, and not in some other way. So this helps developers more than you'd expect.



Quote

Also, in general, I prefer to look at UML diagrams instead of reading text


On the other hand, I'd rather chew my own arm off than try to make sense of UML. To each their own -perhaps providing multiple options would be useful. Fortunately, UML can often be generated - in fact, lots of direct documentation can be generated. You might find that setting up something like Doxygen and learning how to set up repository hooks so that documentation is automatically generated on commit, or else setting up a cron job to regenerate documentation nightly, is a good use of your time,

This post has been edited by jon.kiparsky: 24 March 2014 - 10:49 PM

Was This Post Helpful? 2
  • +
  • -

#4 peace_fixation  Icon User is offline

  • D.I.C Head

Reputation: 45
  • View blog
  • Posts: 198
  • Joined: 01-November 11

Re: What type of developer documents can actually help developers?

Posted 26 March 2014 - 02:20 AM

When I document my own code, I try to:

1) explain what my classes are for, at a high level
2) explain what my methods do, in terms of a contract: give me this and I will give you that, and how they will barf if you give them the wrong thing.
3) explain screwy little bits of unreadable code that I was forced to write because I was too stupid to think of a more elegant solution.

As a fairly new developer, I've struggled coming to grips with other peoples undocumented code, so I try to make sure that I document mine in a way that I would like other people to document.

One other piece of documentation that I would love is at the program, or perhaps module level, and that is a bit of reasoning about what architecture(s) is employed, so when it comes my turn to extend the program and I can get moving quickly instead of spending days poring over code figuring what the hell is going on.
Was This Post Helpful? 2
  • +
  • -

Page 1 of 1