Code Documentation

Documenting code is important. Documenting code is not just commenting code, but also writing pages on how to use your code. Recently I have seen some rookies do things in there documentation similar to:

If you are a user then ask your system admin to set up the server / configuration files

Then never in their documentation include any information for the system admin on how to do so. This kind of documentation is not helpful, you need to have a walk through for each part of the set-up and each part of the usage. Another thing that I have seen recently with projects that include a library or framework is that a link to the installation page for that library is included as the primary source of information about how to install the library that their software depends on.  If you use a library or framework like that then you should try to include a brief summary with a list of instructions on how to install the library or framework under standard circumstances. Then include a link to the external installation page as a backup in case the user needs more information in order to install the package.

While the github wiki is great for documentation it can sometimes be hard to figure out a way to properly display all the information you would like, especially if there is a different way to install the program depending on what operating system you are on. For Briefcase I would like to create a website that has this documentation. A live Briefcase server will also be up and running soon that will allow people to register and test out Briefcase. This will be separate from the dev server that has been running for the past few months, and hopefully more stable.

In other news if anyone is good a graphics design we would love to have you on the project, my claim to fame for graphics design is being able to make the corners curvy and some little photoshop stuff.

– Asher

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: