Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I am currently writing an extended report on a software library I have written. The reviewer will be a professor at my univeristy. He knows basically what I had to do, but the report will be evaluated. I have produced some samples results with the library which I already plan to include in the work. What I want to know know is :

  • What should I write about the library itself?
  • How should I structure it?
  • Which points need to be emphasized?

Also, the professor is as allergic to mundane implementation details as a business manager.

share|improve this question

2 Answers 2

up vote 3 down vote accepted

In my view there are two things important in software documentation/report:

  • Technical documentation, for each function/class you describe the input and output, and what it does. This could also include the class hierarchy if you are using object orientation.
  • User documentation: This includes stuff like:
    • What is the goal of the library, what are the requirements
    • How and why have you designed the library in a particular way. Which design patterns have you used (in case of OOP), or why have you ordered your procedures in a certain way. For your professor this is also important if he wants to see if you can think on a high abstraction level, and not only in the nitty gritty details.
    • Example uses (tutorials) which show a few good examples of how the library can be used. You can link back to design decisions and point out that this example shows why it was a good idea to design in a particular way.
share|improve this answer

Reading your last sentence, probably you have to describe what the library does, instead of how it does it. Including the samples is a good idea; lots of students forget doing it, so you'll probably will have additional points for that. Moreover, you may want to:

  • Write documentation. Samples are great to discover the library, but too hard to use to find a very specific thing. Also, samples tend to never show features which exists, but are rarely used.

  • Some indications about how the library is implemented may still be relevant. It is sometimes unavoidable in order for your library to be used efficiently.

    Example: your library has a following method:

    // Adds words from a single source to a dictionary.
    void AddToDictionary(Source dataSource);
    
    // Adds words in parallel from multiple sources to a dictionary, while opening
    // and saving the dictionary only once.
    void AddToDictionary(IEnumerable<Source> dataSource);
    

    Without proper documentation, I would be unable to know that I must use the second overload for four or more dictionaries, and stick with the basic first implementation for one to three dictionaries, because your library is implemented in such a way that the parallel task will be effective only with a large number of libraries: with less, the time to load and save the dictionary several times will be too small.

  • Last but not least, what are the requirements for your library? If it's written in .NET Framework, do I require .NET Framework 3.5? 4? 4.5? How to deploy it? Just by downloading the file? By downloading the setup and running it? By getting the package and doing one hundred steps in order to make it work?

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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