The company I work for has commissioned a software company to produce a compliance software for several big companies. As part of our contract it is required of them to provide us with src code and documentation in case in the future we want to take over and further develop the project in house or have another company take over.

What are the best practices for software documentation in this case? I.e. What shall I ask of them to provide us for if a 3rd company in the future were to take over?

Right now they just provided us the src code and a auto-generated class document (not even class diagram, just a list of all classes, parameters etc).

I hope someone can point me in the right direction so that I can produce a small document with what our requirements are.

closed as too broad by gnat, amon, Bart van Ingen Schenau, GlenH7, Robert Harvey Mar 12 '14 at 20:24

Please edit the question to limit it to a specific problem with enough detail to identify an adequate answer. Avoid asking multiple distinct questions at once. See the How to Ask page for help clarifying this question. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 2
    unless you define what documentation means you'll get nothing but some autogenerated pages of the sort "setABC: sets ABC" – ratchet freak Mar 12 '14 at 11:18
  • Yes, what I would like from people here is to help me to find out what are best practices to then ask our software company to produce. Someone with more experience than me could tell me what is usually expected from a company that have to take over a project, to have in their hands in order to successfully understand everything and further develop the project. – Manuel Maestrini Mar 12 '14 at 11:34
  • recommended reading: Why is asking a question on “best practice” a bad thing? See also: Where to start – gnat Mar 12 '14 at 11:39
  • Then let me reformulate "Best Practice" as Common practice. i.e. What is generally wished by a software company to have when taking over an existing project in terms of documentation? – Manuel Maestrini Mar 12 '14 at 11:57
  • This is basically a "Gimme da codez" type question. What have you read so far re: national and international standards of software documentation? – Deer Hunter Mar 12 '14 at 12:46

Your vendor is likely to produce the minimum required to fit your definition of documentation.

You will need to spend some time thinking about what kind of documentation you want, and possibly provide them with templates, a wiki, etc. that you want them to use if you don't want to get junk when you are done, and you want it to be easy to update as things change.

What are you likely to need? I think of documents that are accessible to different kinds of people, at different kinds of decision making levels. As ratchet freak said, there is lots of auto generated junk that adds zero value, and you rarely get good information at the very detailed level. Besides, software developers are generally good with the details. You need good documentation for communicating with stakeholders and management.

I think you will want things that explain at different levels of detail. Using the airplane altitude analogy, an example (vary the altitudes for your organization. Since you say that your commissioned software will be used by several companies, you may need more levels):

  1. The 30,000 m view for decision makers at a very high level, for when big changes are needed. (i.e. how this software integrates with existing systems, interfaces, and the major components) You may need more than one of these, if you have disparate existing systems, so negotiation can be done among the several companies you are talking about. Above all, this needs to be brief and clear, with diagrams, and in natural language that a NON-TECHNICAL person can understand.

  2. The 15,000 m view for project teams that might be tasked by the decision makers. You will want this to include the specific differences in the software for the several companies you discuss in the top. There are ALWAYS one-off situations to get from a theoretical design to getting stuff to work. Depending on where the one-off stuff is done (by individual companies, or by this development group), this may get messy. Again, brevity, non-technical language, and diagrams are most useful. It shouldn't matter what language the code is written in, etc. for people to understand this documentation. You want it as a negotiation tool with the user companies, and with the development team.

  3. The 5,000 m view of major code components and how they fit together. Here is the first place where technical language may start to be useful. This is for project teams who have to specify changes, and determine what major chunks of work need to be done. Here is where the developers, designers, and start the back and forth of how things will get done, what parts of the software will need to be changed, etc.

This is what I would want. I'm a developer/integrator in a large multi-site organization. I am often in conference calls with non-technical people who don't care about details, and are trying to understand jargon of IT folks who love the details. You need docs that will communicate the space between big picture and detail, so that you can get everyone in the same place during discussions.

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