11

I'm a software developer at a technology company. I have been tasked with leading the documentation effort for the product I work on. The goal is to produce documentation internal to developer, and the project spills over into the business side, where it covers requirements documentation.

This project is challenging. Specifically, I'm dealing with a product which: - has been around for a long time, at least 6 years. - has no form of documentation other than some small, outdated pieces here and there. - has comments in the code, but they are technical and do not convey any over-arching behavior (even on technical side). - as a consequence of having little to no documentation, is often unnecessarily complex under the covers

In addition, we have not been given a lot of time to work on this project.

I do not have any formal documentation or writing background, training, or experience. I have displayed some ability in writing/communication around the office, which may be why I was assigned to this project.

Please share your advice or recommendation for resources to help me prepare and deal with this project. I'm looking for references to books/website/forums/whatever, to help me come up with the design of a plan with milestones, learn about best practices, task delegation, templates, buy-in, etc.

I'm hoping specifically for resources targeting or giving special mention of introducing good documentation to existing, undocumented, projects.

Improve this question
1
  • 1
    What is the project written in? There are tools for many languages to extract information from function headers and other such things. You won't get anything directly useful out of them, but they might help.
    – David Thornley
    Apr 26, 2011 at 18:03

5 Answers 5

Reset to default
11

I usually use a wiki and just spam stuff up there as I go through the discovery process. Wiki because you get search and history as well as team editing functions. The exact tool is less important than having functioning search and getting everyone using it. Expect it to be very rough at first, but encourage people to make those rough notes as they go because that's all you're going to get at first.

A few things that help a lot:

  • have an editor. You, probably, at first, but if you have the budget make it part of someone's job. Pick someone who is good with language rather than a technical whizz. Edit for clarity rather than perfection - you want to encourage people to write good entries but you will need to guide them at first.
  • use diagrams, but mandate that a relevant tool is used, the image is generated and the source file attached to the page. That way people can edit your image using the proper tool instead of MS-Paint. Few things suck more than a really good diagram built in Visio for which you don't have the source document any more, only a PNG extracted from it.
  • Encourage rearrangement and editing. Even if it's not great at first, you need people to collate information and correct mistakes. Mentor people to do this well.
  • bring this up at your weekly team meetings. Grab the list of recent edits before you go in and praise people who have added anything useful, then ask why those who haven't, haven't.

I have started with a MediaWiki virtual machine image in the past because it's very quick and easy to get started, so people saying "it's too hard" don't get any initial traction.

If your language/environment supports it using JavaDoc/NDoc type tools to extract the comments as you add them is a good low-level approach. But that's less useful than the high-level documentation, and even though the tools kind of support adding higher-level stuff, creating it from nothing using only those tools is unnecessarily laborious.

Improve this answer
4
  • 2
    +1: Wikis are a great tool for this. I've used this approach several times in the last six years for documenting undocumented code in an evolutionary way - and they're so easy, you might be able to get some of your colleagues on board, too.
    – Bob Murphy
    Feb 18, 2011 at 0:36
  • The best thing about wikis is that you can easily get direct input from the people who use and develop the software.
    – HorusKol
    Feb 18, 2011 at 2:37
  • 4
    And answer answers with "great, but why isn't that in the wiki?". If your team isn't used to having documentation it will be a bit of a shock at first. The whole "find the dev who last maintained this and ask them" is frustrating for everyone, but it takes time to get people used to paying it forward.
    – Мסž
    Feb 18, 2011 at 3:01
  • Wikis also tend to be addictive. Once you've seeded one with enough information, and gotten a few people into the habit of updating and checking it, the wiki can turn into a working long-term documentation source for the project.
    – blueberryfields
    Feb 18, 2011 at 4:13
5

If you're documenting the code itself, and not doing end-user documentation, Doxygen is a great tool if your development languages are supported. You run it over your code, and it creates a web site listing all of your functions, classes, etc. Then you can add specially-formatted code comments to group things and add more detail. It's a great way to incrementally document a code base.

Improve this answer
1
  • 2
    +1 for Doxygen. Make sure you enable generation of class diagrams and call graphs. These are invaluable when navigating through a sea of undocumented code.
    – GavinH
    Feb 18, 2011 at 6:16
2

With regard to documenting the code iteself, if Doxygen does not fit your needs, there are many alternative tools available. Wikipedia has a list of nearly 50 such tools and includes details of their functionality and language support.

Disclaimer: I am associated with one of the tools, Imagix 4D.

Improve this answer
1

These are just a few ideas that may be useful on some level:

Have you thought about what form this documentation will take in the end: Will be a Word doc, a DVD, a site with a series of pages breaking down the application, a blogging tool that just rattles off details of the application as one dives through it, using some off-the-shelf document management system like Share Point, or something else? Getting Results would be an example of an on-line book that is a series of pages for example.

What kind of version control and editing process do you want this documentation to take is another issue that may be worth pondering before you get too far into this. How do you want to handle updates and changes.

Feedback is likely to be another interesting dimension on this as whatever you create there will likely be more than a few critiques and how well are those changes prioritized and throttled is another question I'd consider before getting that first version out.

Good luck!

Improve this answer
1

Constructing Documentation, like constructing all other kinds of software, is an inherently complex process.

That's why software developers invented the Agile methods.

Documentation is just software without a compiler. The same methods for software projects applies to documentation projects. Preciesely the same reasoning.

When you write software you start with use cases (or user stories). Documentation is no different.

You prioritize the use cases with an approximate budget.

You have sprints.

You have releases.

You do quality assurance -- testing -- review -- correction and re-release.

It's exactly like building software.

Who are your users? What problems do they have? How will the document solve their problem? Prioritize. Sprint. Eventually, you'll release.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.