X

Week 7: Virtual tour review and writing documentation

Apr 23, 2021

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

Facilities

This section describes all the fun facilities I saw. Picture is from my on
site mentor Peter Alyea.

Color filter

This one scan the image under different colors of lights.

Color filters with many scopes

 

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.

XPS Control Box

Cylinder

The cylinder is used to contain music for phonograph cylinders, one of the
earliest commercial medium.

Cylinder

 

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
background:

– 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.

Writing documentation

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,
etc.
5. Todo list: what should be done for further improve and maintain this
plugin.
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://myusername@github.com/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!

Next Week

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.

Leave a Reply