Before beginning I must apologize for my neglect. Something, I'm not sure which event in life, but something broke my habit of regular blogging. So consider this the beginning of my catch-up blogs to update the world (at least those of you who are interested) in my progress through this course.
This chapter in our text book is about documentation: the purposes, best practices, and standards. Amusingly, I find this subject to be a theme in my coursework this semester. I am also taking an operating systems class in which my professor values good commenting in code so highly that it is actually a part of our grade! Until taking this class I thought I was a relatively good commenter, but I am now finding that I have a lot of growing to do in that area.
In addition to my operating systems class, another class related to software design has been almost entirely about the other type of documentation - the living, cohesive, professional document. I have also found this to be extremely challenging as it requires reviewing and editing the document every time it grows to make sure that it is consistent with itself! As the document grows, so does the complexity and time required to accomplish this task - no wonder programmers hate documenting! Even as I acknowledge its importance and firmly believe that it must be done, I dread going back to reviewing the document every week.
I also found this chapter on documentation to be beneficial because of my team's FOSS project for the semester. We have decided to invest our time in a new activity called Lemonade Stand. This activity is very new and therefore has a lot of room for improvement. One of the first things we noticed is a total lack of documentation for the user! We spent our first half-hour or so simply trying to figure out how to play the game and find the magic keys, since there is no mouse in its GUI! The activity owner is also interested in having better documentation for the activity in its code base and wiki, so we are eager to apply what we are learning to this project.
It may seem surprising that while I spent the first bit of this blog complaining about how hard it is to create good documentation, and to maintain good documentation, yet that is what my team and I are excited about contributing to our FOSS project. Perhaps that gives you an idea of how much we recognize and value the need for it. We have all been part of FOSS projects in the past which have had terrible documentation and it was so frustrating to try to use or contribute to the software. We don't think that anyone should have to go through that frustration, and so we are willing to put in the effort.
As we begin this process I expect that I will be rereading this chapter in even more detail because it is so important to get this right! I'm glad to have the TOS book as a quick resource and guide.
No comments:
Post a Comment