Hi everyone, welcome back to my senior project’s post. In this week, I worked
on another important part, yet underrated part of software developing –
documentation the code. In this post, I will review what I have promised last
week – showing some glimpses about my virtual tour into the Library of
Congress – as well as my experience in writing documentation
Virtual Weaver Tour
This section describes all the fun facilities I saw. Picture is from my on
site mentor Peter Alyea.
This one scan the image under different colors of lights.
XPS stage controller computer
It is a box controlling the motors that rotate the audio media and move either the media(2D) or the optics (3D) to scan the whole surface.
The cylinder is used to contain music for phonograph cylinders, one of the
earliest commercial medium.
New music for processing
My advisor also gave me some new scanned images from other grooved music
sources to process. Here is a list of the songs and their respective
– Sound Effects Library: some sound effects for a old radio show.
– Taking a change on love: a popular song from the 1940 Broadway musical Cabin
in the sky.
– Magnificent cat: a music setting of the biblical canticle Magnificat composed by the German musician Johann Sebastian Bach.
– Greatest story ever told: an American old-time radio religious drama that is related to the Bible.
As mentioned at the beginning of this post, writing documentation for code is
very important, yet it is often ignored. It is important because it provides
guidance for people who are using the code – for users documentation is like
the manual – and for other developers who want to play around with the code or
contribute to make the code better, documentation serves to explain how the
code works, in what aspects it should be improved. However, documentation is
ignore by many developers, simply it takes much time to write a good one.
After finishing many features for my plugin, which still have much room for
further improvement, I realized I need to write something to describe my
plugin for users and other developers.
Structure of a documentation
To write a good documentation, one has to follow a logical structure. For me,
this is my structure for my plugin
1. describe a summary of the plugin function
2. a screenshot for my plugin
3. how to use the plugin, led by a ‘quickstart’ section that makes people get
start with using the code easily.
4. Mechanism – for interested developers, I illustrate how my plugin works –
what data structure did I use, how did I process the tracks’ values,
5. Todo list: what should be done for further improve and maintain this
6. Related plugin: specifically in a plugin-system like weaver, one can
mention the related plugin of one plugin. For instance, since my plugin
‘CombineTracksWeighed’ gets much inspiration from ‘CombineTracks’, I
mentioned it in the documentation.
Details in getting it done
The whole weaver project is hosted on Github. In Github project page, we can
find “wiki”. By clicking into it, we can start editing the wiki pages by
simply following the interface.
The whole process isn’t hard – just follow the buttons like “new page”, “edit
wiki”, and “save”. However, when adding images to the wiki, it is a bit
tricky, since the wiki repository (the files) is separated from the project
one. That is to say, if you want to add an image to the wiki, you shouldn’t
add it inside the weaver project code. Instead, follow those steps:
1. git clone https://firstname.lastname@example.org/username/weaver.wiki.git this
downloads the wiki code on my computer. In this line, ‘myusername’
should be the username of your Github account, and ‘username’ should be
the owner of the weaver project.
2. Open the folder and add your image.
3. Update the repository back to Github.
Then back to the wiki page on GitHub, you can add image now!
On next week, I am going to:
1. Do more literature review on the history of Weaver
2. Write more plugins! I wonder whether the fast Fourier Transform could add
some other evaluation effects in different tracks.