Company Manual

Preface

Teaching software engineering in a classroom setting is an inherently tough challenge.

      Some of the most fun I ever had teaching software engineering was in the Oregon Master of Software Engineering program in the 1999-2000 academic year. It was fun because the program was for working professionals (kind of like a professional MBA program) which meant that for the most part they already understood why this stuff was important. One of my students in OMSE 500 was a section manager at Hewlett-Packard in Corvallis, Oregon. When you're teaching software engineering to someone actively managing 50+ software engineers in a world-class technology company, you'd dang well better know what you're talking about and how it applies in the real world. This guy's garbage meter would go off in 10 minutes if what I was teaching wasn't relevant. I loved the challenge and the environment.

      In the OMSE environment, we didn't do labs or form into teams, or build software. The reason is because everyone in the class was already doing that 50 hours a week. What they needed was some information to fill in the gaps, stuff they could read tonight and apply on the job tomorrow morning. So that was our approach, and it worked beautifully.

      Fast forward to BYU a few years later as I try to bring software engineering excitement to some of the brightest undergraduate Computer Science majors in the world (yeah, that's you).

      My first challenge is that as a group you possess only a fraction of the real experience that my OMSE students had. That means that you may struggle to grasp the relevance (or in some cases, the absolute criticality) of certain topics. You may not understand why I will assert with a straight face that you can solve P=NP and still lose your shirt (and your company) if you don't understand the stuff we're talking about in this class. That's not your fault. It's largely a function of time and experience — most people who have lived in the world of product development get this and most people who haven't, don't. Importantly, most of the people who have lived in the world of product development and who do get this, still have a great deal to learn in order to be successful at it.

      It sets up an inherently difficult pedagogical dilemma: In 16 weeks I can give you a throw-away toy project that will only remotely resemble the real world while risking the loss of focus in certain detailed areas, or I can give you a lab-based experience in which you learn deeply about certain topics while not even attempting to approximate a project experience. In either case, when the semester ends you toss whatever you did, which does not remotely resemble the real world. I've been tweaking the approach now for almost 10 years (sometimes radically), and what you see before you is the latest and greatest incarnation of my attempt to teach software engineering to bright but inexperienced undergrads in the most effective way possible. One significant aspect is the company that will quickly form for the semester.

      As you dive into this company manual, I want you to keep one thing in mind: Nothing that we are doing is fake or mocked-up for your educational edification. It may only last 16 weeks, but what we're doing is absolutely real. We are involved in an on-going project that I call "The 20-Minute Genealogist." I'll tell you more about that in class, and we'll talk quite a bit about what that implies from a product development perspective. The product is real and you have a charter for 16 weeks to push it further down the path to help the 20-minute genealogists out there to be productive in the very limited time they have to do family history work each week.

      As a class you will constitute a company for the next 16 weeks. You inherit all the work of previous semesters and you must work with what you've been given. At the end of the semester, you will in turn leave your legacy to the group that comes after you. Some of the past students who have worked on the project in prior semesters will continue to contribute and participate in a sort of open-source fashion. Those of you who feel so inclined are welcome to continue contributing as well after this semester is over.

      Most of the organization and process that will emerge this semester will be determined by you. The optimal organization in a given semester is a function of the people who show up as well as the particular phase of the project at that point in time. As a consequence, this company manual is intended to give you a leg up in your thinking, without solving the particular challenges and problems that are yours to solve.

      By having something real and meaningful to work on this semester, it's my hope that you pour yourself into the work with a bit more sincerity than you might if you knew it was all a throw-away skills acquisition exercise just to get a grade or just to graduate. In the midst of this live laboratory experience, it's my hope that you find fertile ground to apply the principles and precepts we're learning along the way.

      Prof. Charles Knutson

Introduction to CS428

      Congratulations, you have just been enlisted to work for the ad hoc software development group informally referred to as "Family History Helper." Your minimum tour of duty will include the current semester or term. As some students have done before you, you are welcome to continue contributing after the semester is ended, when arbitrary motivations like grades have begun to fade into a distant memory.

      This manual is a guide to understanding your role in the group and will give you an overall view of the other roles. It will also provide some metrics and a rubric for some specific grading policies.

      The first section (Company layout) illustrates a top down view of the management chain which will be in place to govern the group.

      The second section (Roles and Positions) includes a detailed description of all the company positions and gives specific instruction on roles, deliverables, executions and other related information. You will want to read through them carefully as your first assignment will be to apply for your desired job.

      The third section (Communication) outlines some of the fundamental communication issues that are part of your success as a member of this group.

      What this manual will not do for you, or for the group as a whole, is provide direction on what you produce or how you produce it. This means you will not only need to solve technical problems, but more importantly you will need to solve problems of group dynamics and communication in order to effectively ascertain a correct view of the technical problems that actually need solving.

      The ambiguity inherent in your responsibilities is not fictional or arbitrary — it is inherent in the fact that you just joined an ad hoc software development group. As Jim Collins points out in "Good to Great," the toughest challenge in building a great company is getting the right people on the bus. Once the right people are on the bus, they figure out where it needs to go. You are the people on the bus. You need to figure out where to drive it.

      As the sponsor of this project, I want you to do something extremely cool in the family history domain that will allow me, as an overcommitted wannabe genealogist, to move forward and take names to the temple in as little as 20 minutes a week. As a group you need to figure out how to move "The 20-Minute Genealogist" forward in some definitive way that makes me (and a few million LDS Church members) happy.

      Good luck and God bless you in your efforts.

Company Layout

      The group hierarchy shown on the next page consists of several teams under the direction of one or more students who function in administrative/managerial roles. Each team is led by a team leader and may consist of coders, testers, or other positions (technical writer, marketer, graphic artist, etc.). In any given semester or term, the number and constitution of teams will vary depending on the size and demographics of the class.

      The first assignment for all students is to apply for (and be assigned/hired for) specific positions within the group. The second assignment is for newly assigned team members to figure out how to best function as teams and as an overall organization.

      The sponsor of the project (the professor) and the Executive Manager (the teaching assistant) have very little interest in micro-managing this group, but reserve the right to step in and make executive decisions when there's a critical need. A consultant (the professor) is available to advise managers, team leaders, and engineers on effective organization, communication, and problem resolution. The consultant gives advice, but does not own the outcomes. The consultant becomes involved by invitation of group members.

Roles and Positions

      In the following sections, we briefly describe the various roles that can be played within the software development group.

      As you consider applying for a position, consider your motivations and try to be true to your heart. Some of you will desire a certain position because you already know that you're good at it and can contribute in significant ways in that position (growing your expertise even further). That's great. For some of you, there are positions you've always wanted to try, for which you have no particular experience, but a very strong desire to give it a go. That's also great.

      This classroom setting is a laboratory environment in the best sense of the word. Our cost of failure is significant lower than the average company in industry. That gives us the luxury of trying things just to see if they will work, or to give people an opportunity to grow into roles for which they aren't necessarily the best qualified. It also gives us the flexibility to swap positions mid-semester if we feel that a change is in order and would be positive for everyone.

Director

      The group will probably benefit from one or more directors to function in managerial positions.

      This position requires solid people skills and a strong sense of vision for the group and for the project. An effective director understands that the tremendous variability in programmer productivity is something that he can affect — upset programmers produce below their abilities, inspired programmers produce above their abilities.

      The up-front cost for the first couple of weeks is significant for directors. You've got to quickly work through material that helps you understand better how to manage, and you have to effectively organize a group of several dozen strangers into a software development organization in a matter of days. Be prepared to absorb that cost up front.

      If a director is managing effectively, the week-to-week time hit should be no worse than anybody else in the group. The responsibilities are different, but shouldn't involve significantly more time in a given week.

      The director is responsible for the overall effectiveness of the group under his direction. That means helping to assure that deliverables are scheduled, and that project schedules exist and are managed with appropriate milestones. The director should help with risk management, and with problem resolution. He also provides performance reviews of team leaders that report to him as well as peer evaluations of other executive members of the leadership team.

Team Leader

      Team leaders are responsible for the effective functioning of individual development groups. Their success can best be measured by the success of the individual engineers or contributors on their teams.

      Team leaders should be very aware of the scheduling and productivity realities that face their teams. They should have a clear sense of how productive their team members are, and they should prioritize to facilitating rather than coding (or testing, or writing). However, if things are running smoothly, team leaders are free to contribute at the low level, but not at the cost of lost productivity for the team.

      Team leaders must use effective management tools (such as Pert charts and Gantt charts), and must be aware of the gap between estimates and reality as it affects their teams.

      Team leaders may serve an informational function between engineers and directors, when it is more efficient to do so. But a team leader should never be an impediment to effective communication between team members and anyone else in the organization.

      Every team will have at least a few problems and difficulties during the project. In extreme cases a single significant problem can block an entire team from making progress. Team Leaders should attempt to discover these problems as quickly as possible and work effectively to resolve them.

      Team leaders should work with team members and directors to assess and implement effective and beneficial processes in as appropriate a manner as possible.

Coder / Tester

      Most of the students in the class will function as coders and/or testers on individual teams, reporting to a team leader.

      Philosophies vary concerning how to best organize programming and testing activities. One approach suggests a strict separation between testing and programming to maintain objectivity in the testing and to avoid the blind spots that inevitably arise when developers test their own code. Another approach advocates thorough unit testing performed by developers on their own code with a reduced role for formalized testing.

      Bottom line for this company is that as directors, team leaders, coders and testers, you need to figure out the best way to organize the programming and testing effort this semester.

      If anyone wants to play a strict quality assurance role as a tester, that's fine. Some individuals pursue careers in software testing, and this is a great way to gain some experience. If you want to organize a dedicated test team, that's also fine. If you want to integrate development and testing functions into the same teams, that's also a valid approach.

      While we're fine with individuals testing but writing no production code, we are not fine with individuals only writing code and never testing. You've all had to code to become seniors in this program, but few of you have done more than a smattering of software testing in your time here. We'd like every coder to take a reasonable tour performing software testing responsibilities. Similarly, we want all class members to participate in at least one formal inspection during the semester.

      In terms of stuff to test, obviously the code that gets developed this semester will need to be tested. But keep in mind that the code base from prior semesters is also fair game for quality assurance if you feel that would be productive. Please do your very best to leave a legacy of high quality software and accompanying test cases to future generations of this project.

Tech Writer

      The technical writer is the documentation lifeline of the company. His or her realm of responsibility may encompass almost everything on the forums and the Wiki, as well as the help guides and textual content that the user sees when they use The 20-Minute Genealogist.

      It is necessary for the tech writer to have full permissions to edit and organize the Wiki and Trac.

      There is typically only one technical writer for the company in a given semester. Below is a list of some of the important tasks a tech writer may assist with:

  • Project website management
  • Document editing (not necessarily writing)
  • Maintenance of announcements and communication on the Wiki
  • On-going organization and refinement of the Wiki and Trac
  • Movement of useful content from the forums to the Wiki
  • Product documentation (internal to development as well as external to users)

Marketer

      The 20-Minute Genealogist is intended to help a fairly large swath of the LDS Church population to manage and organize their family history research material. The market includes teens and twenty-somethings who have no fear of technology; 40- and 50-somethings who are comfortable with technology but unbelievably busy with work, family and church callings; and 60- and 70-somethings who speak technology with a very thick accent and fall somewhere between intimidated and terrified when they encounter a keyboard.

      It's imperative that we understand the market so that we build software that actually meets the needs of the widest possible set of potential users. Marketers help us to target the right audience with the right features, gather data to confirm our hunches, and help set priorities for subsequent semesters. They generally don't directly impact the efforts of the current semester because the turnaround time between them gathering information and development teams beginning to implement their recommendations introduces an excessive latency in a single semester.

      In addition to gathering information from potential users of the system, marketers also work to get the word out, focusing on ways in which we can advertise and otherwise spread the word about The 20-Minute Genealogist.

      We have had MBA students in this class in the past, and we hope to have more in the future. However, prior experience in marketing is not a requirement to play this role in the company. If you're inclined to play this role, and willing to do reading and training to come up to speed, you're welcome to sign up as a marketer.

Graphic Artist

      We understand that we won't always get a qualified (or interested) graphic artist in a given semester, given the luck of the draw (no pun intended). However, the function is important and can be beneficial if someone is qualified and interested in assuming this position.

      A graphic artist can assist teams with feature design, and can help marketing with advertising and promotional materials. A graphic artist can also help with product design and layout wherever appropriate.

      An individual assuming this responsibility must be self-motivated and able to work with little supervision. The reporting structure for the graphic artist is something that has to be determined as the semester gets underway.

Communication

     Introduction

      Communication is one of the most difficult challenges you will face in this organization. You need to be able to quickly communicate complicated ideas to multiple people: those you are currently working with and those that will read your work in subsequent semesters. Communication is a critical part of business and is a large part of what makes or breaks professional organizations. This chapter has been written as a guide to help get you started.

      You will find that there are problems inside this company. That's because it's populated with ordinary folks like yourself trying to figure out how to get something good done in a limited time frame with limited direction from the sponsor. Many times you will think you have a solution to the problem. DON'T HOLD BACK ON VOICING YOUR IDEA. You might think to yourself that it's none of your business or it's not your job; this is false. If you see a problem, you own it! Failures that you saw coming but did nothing about are at least partially your fault. You are responsible for making sure the problems you find are solved. No one is stopping you but yourself.

      Of course, in order to have influence, you'll need to apply (and possibly develop) positive communication skills. We challenge you to take this aspect seriously. If you do, it has the potential to bless you in your professional career for many years.

     The Project Wiki

      The Project Wiki (https://twenty.cs.byu.edu/wiki) is one of the ways information is passed between semesters and across the organization. It is essential to keep it up to date. Everyone is responsible for keeping this updated. The quicker and clearer ideas can be passed around the company, the better it will run.

      This also means that everyone in the company is responsible for utilizing the wiki as a fundamental communication source. Use some of your billable time each week to keep up with the latest developments across the development group.

      You will find documentation on the wiki explaining how stuff works and how to do other stuff. If you don't understand what the documentation is trying to say, figure it out and then edit the document so it's more clear for the next person to come along. Similarly, if you get an error working with a HOWTO page, you are responsible for finding the answer and then adding a section that explains the fix. Be liberal with your changes. You cannot break the wiki because it can always be rolled back. Constant editing yields quality pages. It's also an exercise in taking responsibility rather than sitting around waiting for someone to fix things for you.

     Conclusion

      During this semester you will hopefully begin to understand more clearly some of the key concepts from The Mythical Man Month and Peopleware; Communication is far more costly than you may have ever imagined. At the same time, effective communication is imperative to creating a good product and sharing a common vision. You are being given a great opportunity to work as teams during class, so make sure that you use the time well to line up your sights and move together. Communicate greatness and you will learn more than just Computer Science, you will learn how to motivate people and work as a united team; you will learn one of the most critical lessons of Software Engineering.

Bibliography

  • [1] Brooks, Frederick p. Jr. Mythical Man Month. Addison-Wesley, California, 1982
  • [2] Collins, Jim. Good to Great. HarperCollins Publishers Inc., New York, New York, 2001
  • [3] DeMarco, Tom and Lister, Timothy. Peopleware. Dorset House Publishing Co., New York, New York, 1999.
  • [4] L. Lamport. LATEX A Document Preparation System. Addison-Wesley, California, 1986.
  • [5] McCarthy, Jim. Dynamics of Software Development. Microsoft Press, Redmond, Washington, 2006