Alongside ObMimic and various other tasks, I do some occassional “freelance”-type work. This tends to be quite varied, but is typically things that need a skilled Java developer but aren’t the core “development” work for a project (things like code reviews, investigating and fixing long-standing but low-priority bugs, cleaning up existing code bases against FindBugs etc).
One recent request was to write the Javadoc for an existing body of code (which had a few unit tests, but no existing Javadoc or other documentation). I was rather surprised that anyone would outsource such work, but in retrospect it made a great deal of sense for the particular project involved.
I’m now wondering whether this is a more widespread practice, and whether anybody has any particular views or experiences with outsourcing of Javadoc that they might like to share (from either side of the fence).
Personally, I’ve come to regard Javadoc, code and tests as needing to be developed together and feeding off each other. The Javadoc then acts not only as documentation for users of the code, but also as a specification that the code has to conform to – with the tests checking this.
I’m also used to writing Javadoc that has to be of “publishable” quality (in particular, because having comprehensive, detailed and precise Javadoc is a critical part of my own ObMimic product).
So it initially struck me as rather strange that someone would want an outsider to step in and write their Javadoc retrospectively.
However, as a result of this work I can see several reasons why this can be a good idea in some circumstances:
- In this particular case, the client involved can communicate reasonably well in English but it isn’t their native language. They weren’t confident of being able to write sufficiently clear Javadoc in English, so wanted it done by a native English speaker.
- Writing useful and accurate Javadoc is a quite different skill from developing and testing code. Not all developers are good at it, and not everyone is happy to do it. Even where developers do write Javadoc, it doesn’t seem uncommon for this to be rushed and left somewhat crude and incomplete.
- Writing and proof-reading Javadoc can be very time-consuming, and can be somewhat of a distraction when one is busy developing code and tests. Where Javadoc is going to be needed for public consumption or future reference but isn’t particularly necessary for the development process itself, it might be more efficient to free developers from the burden of having to write Javadoc alongside everything else, and instead tackle it entirely separately.
- Whilst large organisations might be able to dedicate appropriate people to writing Javadoc, this isn’t always feasible or cost-effective. Arguably, if someone has the skills to sufficiently analyse and understand the code and also to produce good quality documentation, they are probably too valuable to be spending their time writing Javadoc.
- An external, independent person can write the Javadoc free from any pre-existing knowledge or assumptions that might be taken for granted by the code’s developers, and can more easily take the viewpoint of a typical user of the code.
- Having an outsider work backwards from the code to produce detailed Javadoc can provide a useful code review at the same time, and can perhaps spot some types of mistakes and oversights that might go unnoticed during normal code reviews.
On the other hand:
- I still tend to think that the ideal – when possible and cost-effective – is for developers to write their own high-quality Javadoc as an intrinsic part of writing each piece of code and its accompanying tests.
- Outsourcing the Javadoc presumes that the relevant source code can be made available, which may raise security and/or legal issues.
- It can be quite difficult and slow to take existing code and fully investigate and determine its actual behaviour, discern its overall intent, and then write suitable explanations, guidance etc.
- To a large extent the effort involved and the quality of the results depends heavily on the nature and quality of the code; if the code is a mess of meaningless names and illogical design and behaviour, it’s going to be incredibly hard for anyone to derive accurate and logical Javadoc from it.
- Even if the writing of Javadoc is outsourced, this will inevitably require some degree of communication, discussion etc (e.g. to settle on what degree of detail is required, resolve questions about the code’s intent or possible bugs etc). At the very minimum, somebody will at least need to check the results.
- Writing Javadoc isn’t usually a once-only exercise; if writing the Javadoc is outsourced, who updates it when the code is subsequently changed?
- For small projects, a single person might be able to write a full set of Javadoc in a reasonable timeframe; but for larger projects the amount of work involved might require multiple people or a prolonged effort. Beyond a certain size outsourcing this work might simply not be practical or worthwhile.
Obviously, the need for Javadoc and the quality of Javadoc required depends on the project. For example, for a closed-source Java library the Javadoc might be the only thing a user of the library has to go on, whereas for an open-source library they can always fall back to looking directly at the code; and for purely “in-house” applications and non-“library” code maybe there’s no need for Javadoc at all.
Similarly, the practicalities, relative costs and other pros and cons of outsourcing Javadoc will differ between projects and circumstances, and various trade-offs are always possible. For example, sometimes it might make sense to draft basic or outline Javadoc in-house and then use somebody else to just review, improve and finish it.
With regard to cost, I imagine there are no end of people around the world that could offer to write Javadoc at a low price. However, it seems to me that below a certain level of skill and quality there’s no point writing Javadoc at all, and that quite a high degree of programming, analysis and documentation skills are required before it becomes worth doing (and as noted above, the author’s language skills can also be relevant). Conversely, I imagine that using “high-end” consultancies or software houses for such work could be excessively expensive.
Is there a sweet spot somewhere between those extremes for relatively high-skilled freelancers? Perhaps the ideal is a freelancer with all the necessary skills but charging less than the full cost of using your own in-house developers. But are there many suitably skilled people available and willing to do such work – aren’t most such people in full-time jobs, or loathe to take on such relatively laborious tasks?
Overall, I’m curious as to whether outsourcing the writing of Javadoc is relatively common or unusual, and whether there’s any broader demand for such work. Does anybody have any views or experience of this? Is there anyone out there actually doing this as “freelance” work? Is there anyone who has tried outsourcing such work, and if so how did it go?
Recent Comments