A short link to this page is https://wiki.list.org/x/17891981

Clear message
Rendering of reStructured text is not possible, please install Docutils.
Working with Milestones
=======================

Copyright 2016, Stephen J. Turnbull.  The activity descriptions in the
tables are copyright by their authors and used by permission.  **It
follows that all rights are reserved,** *i.e.*, **copying and
redistribution of this document is not permitted at present.**

.. student: yland
.. period: 1st 3 weeks

Here are some comments about two students' schedules.  Note that
inclusion here does not imply any evaluation of the quality of the
proposal itself, and I've avoided making comments about specific
designs.

In each case I've picked up the first weeks of coding.  They are
roughly representative of the full schedule for each student.  It may be
hard to guess exactly what is intended by each activity, but that's OK
in a schedule as long as you know what you mean (have a design) and
communicate it to the mentor in some way (often in a separate section,
though we don't have a specific format for that).

The first student doesn't provide any milestones.  Although the words
are active, all of the "create" tasks could be rephrased as
"deliverables".  In terms of Python they each amount to a single class.
All could be turned into milestones by adding concrete events that are
objectively verifiable, such as "unit tests covering all designed
functionality pass and merge request posted".  But see comments on
specific activities.

+----+------------------------------+--------------------------------------+
| Wk | Activities                   | Specific comments                    |
+====+==============================+======================================+
|  1 | - Create integer enumeration | - *Integer enumeration is a good*    |
|    |   for options.               |   deliverable, *but it's way too     |
|    |                              |   small to be a good* milestone.     |
|    |                              |                                      |
|    | - Create new model for       | - *The unsubscribe model could maybe |
|    |   unsubscribes               |   function as a milestone if methods | 
|    |                              |   and tests are included, but it's   |
|    |                              |   not a blocker, you're not in       |
|    |                              |   trouble yet if it's not done - you |
|    |                              |   might be doing something else, and |
|    |                              |   it's likely that you really can't  |
|    |                              |   finish until you see how it        |
|    |                              |   interacts with other components.*  |
+----+------------------------------+--------------------------------------+
|  2 | - Update the                 | - *These two activities also leave   |
|    |   Member/subscriber model    |   connections to related tasks       |
|    |                              |   dangling, which is a problem for   |
|    | - Identify mode of           |   milestone definition because you   |
|    |   subscription and           |   may need to revise the methods or  |
|    |   unsubscription             |   add members, or even redesign or   |
|    |                              |   refactor in light of problems due  |
|    |                              |   to interactions with other parts.* |
+----+------------------------------+--------------------------------------+
|  3 | - Store information in the   | - *With models added, we can now add |
|    |   database                   |   functions to store the information |
|    |                              |   in them.  This should allow some   |
|    |                              |   amount of system test (perhaps     |
|    |                              |   accessing the database via a shell |
|    |                              |   for that database), and completes  |
|    |                              |   a cohesive unit of functionality.  |
|    |                              |   There are no "loose ends", except  |
|    |                              |   retrieving the data, but that can  |
|    |                              |   be treated as a milestone of its   |
|    |                              |   own.*                              |
|    |                              |                                      |
|    | - Create class to access     | - *"Class to access information"     |
|    |   information                |   might be a second milestone        |
|    |                              |   if the appropriate units tests are |
|    |                              |   passing and merge request posted   |
|    |                              |   are added as conditions to the     |
|    |                              |   milestone.*                        |
+----+------------------------------+--------------------------------------+

Note that these two milestones both in Week 3 represent very different
amounts of work, and in quick succession.  Neither condition is
desirable, but you may need to accept it, and the risk that you get
quite far behind schedule by the time you reach the first milestone and
can measure how much slippage you've suffered.  On the other hand, very
often you can "refactor" or reorder your schedule to allow your
milestones to be more evenly spaced.

Another way to deal with this situation would be to use each "model
creation" as a milestone, and be very disciplined about the order in
which you do them.  (You can also use a technique called "earned value"
to reorder milestones "on the fly" when problems or opportunities to do
a better job pop up.  See the end of this page for a reference.)

The point about "measuring slippage" is *very* important.  Knowing that
you're behind is not that hard.  The problem that sharp-edged (meaning
"clear and objective") milestones help to resolve is the tendency to
make excuses, start on future tasks before you finish early ones, and
skimp on features and testing -- omissions which all will come back to
use (much!) more time than expected later.


.. student: aditi
.. period: 1st 3 weeks

The second student adds more detail as well as various "meta" tasks that
involve "talking about" the project rather than "writing code for" the
project.  This is to a great extent a matter of personal style, but as
you probably feel yourself, it's more self-contained and in that sense
easier to understand.  As a matter of "rational" tradeoff, of course the
issue is that if this style doesn't come naturally to you, you may be
find it much less effort to use the more terse style of the first
student, leave detail to another section, and leave "meta" activities to
be "read from between the lines."

+----+------------------------------+--------------------------------------+
| Wk | Activities                   | Specific comments                    |
+====+==============================+======================================+
|  1 | - Completion of  reading and | - *"Understanding" will never be a   |
|    |   understanding the codes.   |   good milestone because it's not    |
|    |                              |   objective by definition.*          |
|    | - Setup Postfix to send and  |                                      |
|    |   receive mails on the       | - *With the inclusion of specific    |
|    |   mailing lists.             |   testing tasks, "setup Postfix" is  |
|    |                              |   a milestone, but quite small.*     |
|    | - Discussion of my approach  |                                      |
|    |   to implement the feature   | - *"Discussion" isn't objective.     |
|    |   of Dynamic Sublists with   |   BTW, it's not a* deliverable,      |
|    |   the mentors.               |   *either.*                          |
|    |                              |                                      |
|    | - The main aim of Week 1 is  | - *It's called "the main aim" but    |
|    |   to design the structure of |   really it's two goals.  This is a  |
|    |   Dynamic Sublists and       |   bit pedantic in this case, but be  |
|    |   getting familiar with      |   careful.  You can hide quite large |
|    |   Dynamic Sublists in        |   tasks with "and ... in general",   |
|    |   general.                   |   as well as leaving crucial         |
|    |                              |   dependencies implicit.*            |
|    |                              |                                      |
|    |                              | - *"Submission" is a good milestone  |
|    | - **Milestone:** submission  |   event.  You have a message in your |
|    |   of design documentation to |   sent folder, the mentor has one in |
|    |   mentor.                    |   her inbox, very objective.  But    |
|    |                              |   the content of "design             |
|    |                              |   documentation" is unclear.  Here   |
|    |                              |   it's not a good idea to leave such |
|    |                              |   definitions to another section.    |
|    |                              |   Each milestone should be clearly   |
|    |                              |   defined in a self-contained        |
|    |                              |   statement.*                        |
+----+------------------------------+--------------------------------------+
|  3 | The aim for week 3 is to:    | - *As with the first student, the    |
|    |                              |   word "create" strongly suggests a  |
|    | - Create an interface in     |   deliverable.*                      |
|    |   Postorius that will accept |                                      |
|    |   the mailing list name or   | - *"First task" refers to a separate |
|    |   id and will store essays   |   description.  This is OK, but      |
|    |   in the database.           |   "completion"* strongly *suggests a |
|    |                              |   milestone can be defined.  So in   |
|    | - Completion of the first    |   this case I would recommend to     |
|    |   task ie essay              |   reword in a "self-contained" way   |
|    |   implementation with the    |   so this "completion" can be used   |
|    |   reviews and testing        |   as a milestone.*                   |
|    |   process.                   |                                      |
|    |                              | - *Maybe I'm beating a dead horse at |
|    | - **Deliverable:**           |   this point.  But ending with a     |
|    |   documentation of this      |   "deliverable" at this point, given |
|    |   design.                    |   the two previous comments, did     |
|    |                              |   confuse me somewhat.  It's not     |
|    |                              |   "fatal", but confusing readers     |
|    |                              |   will never improve your grade.*    |
+----+------------------------------+--------------------------------------+

There's not much to say here that hasn't already been written.

References
----------

I will take these last few lines to recommend Watts Humphrey's books on
the "Personal Software Process".  (These are the books where you can
learn more about "milestones", "earned value", and many other ways to
improve your time management, as well as planning and quality control of
your own product.)

Humphrey, Watts [1995].  *A Discipline for Software Engineering*.
Addison-Wesley.  ISBN-13: 978-0201546101.
``http://www.amazon.com/Discipline-Software-Engineering-Watts-Humphrey/dp/0201546108``

*Discipline* is sort of the grand-daddy, mostly of interest because it
gets cited.  Way too detailed for almost anybody (unless you have to
write plans to US DoD specs, or just like programming yourself as if you
were an Intel chip).

Humphrey, Watts [1996].  *Introduction to the Personal Software Process*.
Addison-Wesley.  ISBN-13: 078-5342548099.
``http://www.amazon.com/gp/product/0201548097/``

Humphrey, Watts [2005].  *PSP(sm): A Self-Improvement Process for
Software Engineers*.  Addison-Wesley.  ISBN-13: 978-0321305497.
``http://www.amazon.com/PSP-Self-Improvement-Process-Software-Engineers/dp/0321305493/``

*Introduction* and *PSP* cover almost exactly the same ground.  Some
explanations and methods are updated in *PSP*, and a very few new ideas
and methods are presented.  But it's not worth paying a premium for.