• Advertisement
Sign in to follow this  

Advice on documentation of software builds?

This topic is 4267 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

Hello all, I'm working at a software company as a summer technical student and am doing documentation of their software build system. This is the process in which source files are compiled and packaged into products that can eventually be shipped to customers. I've been doing this for nine weeks now and have a fair amount of info (all of which is confidential so I can't go into the details), but I was wondering if anybody has advice on doing this sort of documentation. The source I am dealing with is both java and C/C++. Perhaps someone has seen this sort of doc in the past or has done something like this in the past? Also, does anyone know a good explanation for how InstallShield works? I know that all of this is fairly vague, but any comments would be helpful. Thanks.

Share this post


Link to post
Share on other sites
Advertisement
Well, I guess the first question to ask yourself when writing anykind of document like that (and an answer to which will help us help you [smile]) is "Who is the intended audience?" I know this can be kinda vague and everybody says it, so it loses its impact a bit, but yeah, it's important. So the first thing we want to figure out is this: is this document intended for internal or external consumption? Is the build tool going to be distributed to someone outside the company along with the tool itself? And if so, is it going to be distributed as a standalone tool, or just a thing to help them build the main piece of software that your company sells? Either way, with anything that's going to be used outside the company, you want to put as many details about the operation of the tool as possible, including caveats and anything extraordinary one needs to make it work.

I suspect, however, this tool if for internal use only. In this case, you still need to consider: is this document for developers that are only going to use it? Or maybe at some point they might want to look at and modify the code of the tool itself for some reason? In the latter case, you might want to not only document the way the tool woks, but also talk about how it is implemented.

In general, when I write a document like that, I put first a little overview section which lists what the tool does and a little about how it does it, and then one section for every major bit of fucntionality, including a detailed description as to what's going on, and any gotchas the user may encounter, and then maybe a separate section for caveats that didn't fit anywhere in particular.

So, for example, if I were writing a document for an imaginary tool, I would first put a section of overview. In there I would say something like "The such-and-such tool is used to build software and package it for distribution to customers. It takes in a directory that is the root of where the project to be built lives and attempts to compile all the source files it recursively finds. Once the compilation succeeds, the tool will collect all the project's resource files and package them into a distributable archive. Once all the resources are collected, the tool generates an MSI installer ready to be dsitributed to the customers, which contains all the necessary executables, resources, and configuration." Ya know. Something like that. Adapt to your needs, and expand a bit, like what the heck is an installer. ;)

Now, you got yourself an overview like that. Read over it and figure out what are the major steps. If you read my fictitious overview, you will notice there are four major bits of functionality in the tool: analyzing the directory structure to identify source files and resources, compiling sources, packaging resources, and generating an installer. So I would put a separate section in the document for each of those. The analyzing directory structure bit could like something like this: "The tool expects a directory command-line parameter at startup. This parameter will be used to locate the project to be distributed. If the directory pointed to by this path does not exist, the tool will quit with an error (error description goes here). Once the directory is located, the tool will recursively go through each file in this directory and its child directories. It will consider all .java, .c, .h, .cpp, and .hpp files to be source files, and they will be included in the compilation process. It will consider all .txt, .gif, and .help files resources, which will be packaged for release with the executable. Files with other extensions will be ignored." Notice here I would list any error that can be encountered during this stage of the execution of the tool, and if it's not obvious, explicitly say what may be a possible solution. Like, as above, if the directory doesn't exist, it's kind of obvious that you have to... you know... provide a valid directory. ;) However, in some tools I've seen, they might rely on some sort of environment variable. So, say our imaginary tool expected an environment variable telling it which version of the java compiler to use. Then definitely stick that into the section on the compilation process, and tell the user what the error might be if the environment variable is missing, how to fix this, and what to do if they can't set environment variables (contact sys admin, blah blah blah).

Also, this reminded me, if the tool requires special start-up procedures, like it requires (or even supports) a bunch of startup command-line parameters, it would probably be a good idea to dedicate a separate section to enumerating the possible parameters, what kind of values they need, what happens if they are not provided, and such.

Hmmm... What else... Right, so if there is anything at all quirky about the tool, make sure to mention it. Like did you just get it and it magically worked on your computer? I bet you had to do something to make it work. ;) List it.

And in general, if you are in doubt whether something is obvious enough to be ignored in the document... It isn't. ;) First of all, remember there are people out there who aren't as smart as you, so if something is obvious to you, it may not be to them. Secondly, and even more importantly, recognize that often times things only seem obvious to you because you've looked at them for a long time. Someone who hasn't seen the tool before will be easily confused.

Finally, if there is any kind of development involving this tool envisioned for the future, like some sort of plug-in system to support other compilers, make sure to write about how one might go about developing something like that.

Wow... I've just written a document about writing documents. :) Let me tell you: once you've written a few documents thinking just about how to make 'em long enough to satisfy the superior, once you have that experience... You'll be praying for the ability to write concisely, instead of producing long-wided discussions that are too huge for anyone to read without going insane. ;)

... Hope that helps. :D

--
Vovan

Share this post


Link to post
Share on other sites
Thanks for the prompt reply. Everything you said is extremely helpful. I especially like your perspective on how to organize the document.

Part of the reason I've been getting bogged down is because I've mostly been reading log files, figuring out how the processes that wrapped around the build tool to automate it worked, figuring out how our build machines work, and talking to people on the build team. Early on, I should have focused more on how the build tool itself worked, such as the command line arguments and the syntax for defining build scripts. Another problem was the fact that this was a very broad assignment (especially for a HS grad with limited experience in Comp Sci). The outline that we devised for this project during one of our early meetings was:

1) introduction
2) general audience (managers and executives)
3) content for developers
4) content for build team

I only got through parts 1,2, and 4 and along the way, everyone kept giving me conflicting advice how to organize these sections internally. Plus, the tool was written in C, but I don't know C, so I couldn't read the source. Well, enough complaining for today.

Right now I have 16 pages of random information, but not nearly enough info on the inner workings of the tool itself. If I could start over I would focus more on the inner workings of the tool for use by people on the build team and follow your outline.

Anyways, thanks for your advice. Doing this documentation has been a great learning experience, and at least I got some cash to pay for college.

dli200608

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement