Subject: [Fwd: [gentoo-managers] development standards for key strategic
	projects]
From: Daniel Robbins <drobbins@gentoo.org>
To: esammer@gentoo.org
Content-Type: multipart/mixed; boundary="=-vGGsMI5mjLq/3omZJrik"
Organization: Gentoo Technologies, Inc.
Message-Id: <1075939314.25352.1554.camel@wave.gentoo.org>
Mime-Version: 1.0
Date: Wed, 04 Feb 2004 17:01:54 -0700


--=-vGGsMI5mjLq/3omZJrik
Content-Type: text/plain
Content-Transfer-Encoding: 7bit


--=-vGGsMI5mjLq/3omZJrik
Content-Disposition: inline
Content-Description: Forwarded message - [gentoo-managers] development
	standards for key strategic projects
Content-Type: message/rfc822

Received: from lists.gentoo.org ([128.193.0.34] helo=eagle.gentoo.org) by
	smtp.gentoo.org with esmtp (Exim 4.24) id 1AoWbV-0001Mq-QG for
	drobbins@gentoo.org; Wed, 04 Feb 2004 23:38:45 +0000
Received: (qmail 12815 invoked by uid 50004); 4 Feb 2004 23:38:45 +0000
Mailing-List: contact gentoo-managers-help@gentoo.org; run by ezmlm
Precedence: bulk
List-Post: <mailto:gentoo-managers@gentoo.org>
List-Help: <mailto:gentoo-managers-help@gentoo.org>
List-Unsubscribe: <mailto:gentoo-managers-unsubscribe@gentoo.org>
List-Subscribe: <mailto:gentoo-managers-subscribe@gentoo.org>
List-Id: Gentoo Linux mail <gentoo-managers.gentoo.org>
Reply-To: gentoo-managers@lists.gentoo.org
X-BeenThere: gentoo-managers@gentoo.org
Delivered-To: mailing list gentoo-managers@lists.gentoo.org
Received: (qmail 4223 invoked from network); 4 Feb 2004 23:38:44 +0000
From: Daniel Robbins <drobbins@gentoo.org>
To: gentoo-managers@lists.gentoo.org
Content-Type: text/plain
Organization: Gentoo Technologies, Inc.
Message-Id: <1075937958.25349.1538.camel@wave.gentoo.org>
Mime-Version: 1.0
X-Mailer: Ximian Evolution 1.4.5 
Date: Wed, 04 Feb 2004 16:39:18 -0700
Subject: [gentoo-managers] development standards for key strategic projects
X-Spam-Checker-Version: SpamAssassin 2.60 (1.212-2003-09-23-exp) on 
	emu.gentoo.org
X-Spam-Level: 
X-Spam-Status: No, hits=0.0 required=4.0 tests=none autolearn=ham
	version=2.60
Content-Transfer-Encoding: 7bit

Hi All,

Here is a first-draft comprehensive document of the standards we are
using for portage-ng development, and what I think we should use for all
key strategic projects for Gentoo. Note that I am not an expert in
established software development practices, but I will try to cover what
I would consider essential.

These standards should benefit nearly any Gentoo project, but are
especially critical for projects where failure could significantly hurt
Gentoo, and perfect execution could be a tremendous benefit to Gentoo.

These standards are being used for portage-ng development.

Goals
=====

The goal of these development standards is to provide a template that,
when followed, will provide the best possible results for Gentoo as a
software development project.

Identify Target Audience
========================

The first step of this process is identify the "target audience," those
people for whom you are developing for. This may be a relatively small
group, or it could encompass all Gentoo users. It may even include
people who are not currently Gentoo users.

Development Roadmap
===================

Develop a tenative roadmap that sets general completion dates for:

1) project start (public invitation)
2) initial work on design/requirements doc
3) completion of design/requirements doc (should be at least a month
after #2)
4) implementation proposal process
5) review process
6) prototype implementation
7) final implementation

These steps are described later in this document.

Invite Participation
====================

The next step is to invite public participation in the effort. The best
way to do this is to start a decicated mailing list devoted to this
effort, or to use an existing "special purpose" mailing list for this
purpose. Ask anyone who wants to be involved to join this list. Make
sure that your invitation extends to your entire target audience, and
consider posting a www.gentoo.org news item or GWN article about the
effort to invite participation.

Document Design Goals and Requirements
======================================

Now that you have a group together, you need to define requirements for
the development effort, and this should be a community process that
invites the participation of as many of your target audience as
possible. You are catering to the needs of your target audience. What do
they require? Documenting requirements is the *critical* step of the
software development effort, and there are many important details and
caveats in this section, so please read it carefully.

Let's start with some definitions:

"hard requirement" - a requirement that any final product must meet in
order to be considered successful. If your development effort is under
time pressure and a hard requirement is not yet met, then your work
cannot be considered complete and may fall behind schedule. If there are
technical difficulties with the hard requirement, you will need to find
a way to address them in order for the entire development effort to
succeed. Dropping the requirement is not an option. No tradeoffs or
negotiation are acceptable.

"soft requirement" - a requirement that is more open to tradeoffs and
negotiation. It would be beneficial to meet this requirement, but not
meeting it would not doom the entire project to failure.

"design goal" - the requirements are there do define needed
functionality. Design goals are intended to clue people in to the
various qualities that should be in the final result that may not be
clearly spelled-out in the requirements. Generally, design goals should
give an overview or "picture" of what is being developed, without going
into too much detail. For example, "foobar should be an easy-to-use,
modular program that helps people to remember important dates." That
would be a design goal. Maybe a requirement for this effort would be "to
have a natural language interface." This would reflect the design goal
of "easy-to-use."

Requirements the "Gentoo" way
=============================

You now have a group of people together with valuable knowledge. Now,
you need to figure out what they need. Here are *key* steps to follow in
this process.

1) Super-important -- no implementation details allowed

*Always* strive to determine the least-common-denominator when accepting
requirements from users.

One person may say "I want to have a --foo option that makes this
program list everything sideways." This is not a pure requirement
because it contains implementation details. You need to press the user
-- what is he or she actually trying to *do*? Why does he or she need
that functionality? "I need to be able to get a full view of all the
important dates of the month in an easy-to-read format."
*That* is the real requirement. Put that in your requirements document,
but leave out the irrelevant implementation details regarding the "--foo
option" and "listing everything sideways."

The conversation may go like this:

"I want to have a --foo option that makes this program list everything
sideways."

"OK, interesting idea. Is it really important that this feature be
triggered by the --foo option?"

"No, I don't care about that. I just want to be able to tell the program
to list everything sideways."

"OK, then the --foo option in itself isn't a requirement. Now let me ask
you about this 'sideways listing' idea. Why exactly do you need that
functionality?"

"Because I need to see all the important dates for the month on the
screen at once."

"So, hypothetically, let's assume that we find a way to display all the
important dates for the month on the screen at once, but they aren't
displayed sideways but some other way. Would this be acceptable to you?"

"Yes. As long as I can see all the important dates of the month and it's
easy to read, then I'm happy."

You've just taken user feedback and converted it into a raw, unpolluted
requirement. You've stripped away the irrelevant details and gotten to
the heart of the matter. Now, record this requirement in your XML design
goals and requirements doc. Now the people architecting the code will be
free of any artificial and unnecessary constraints and paradigms.

User feedback will often be framed in terms of features in an existing
program. They are very often littered with irrelevant implementation
details that do not belong in a design goals and requirements document.
They may help to explain the underlying concept, but are not really a
requirement.

 2) mailing list posts are not enough, irc is not enough! XML!

On mailing lists or irc, people will suggest good ideas, and you will
think of good ideas. There will be conversations between people, and the
process of defining requirements will begin.
That's great. However, *any good ideas need to be transferred to an
official XML design document.* *Do not* just leave them on the lists.
They will be forgotten, or worse, re-hashed endlessly. 
In order for the conversation to move forward, salient points and
concepts needs to be rolled into an official XML document. The
discussion needs to be about the XML document, to give the discussion a
focus.

You need to have someone who is responsible for transferring
requirements *from* the list *to* an XML document that is publicly
viewable. When the idea has been transferred to XML, post a message to
the list saying "I've added ideas x,y,z to the XML document. Please take
a look."

This is important for a couple of reasons. First, the XML is your
official design document. The mailing list is only appropriate for
conversations. And your target audience needs to see their requirements
and the requirements of others in the context of the entire XML design
document to see how everything fits together.
Sometimes, ideas will be combined or split up by the time they hit the
design doc.

They need to be able to read your interpretation of their ideas. The
design document gives a complete picture of the status of the
requirements and design goals so far.

The key rule is that *if something is not documented in XML on a
gentoo.org design doc, it is not part of the design.*

 3) When your design goals/requirements document is done

Your design goals and requirements XML document needs to get to the
point where it is done. The first step is to ensure that you have
received sufficient requirements and design goals from the target
audience, so that all bases are covered. Generally, work on the design
doc should take no less than 30 days of true public participation.

*Your completed design goals/requirements doc should have absolutely no
implementation details, just raw requirements and design goals*

Here's how you'll know when your design doc is really done. Ask yourself
this: could you hand it to someone and say "implement this however you
want -- I don't care. As long as you meet the documented requirements
and design goals, I will be happy with the result." 

Ack! But you don't want it implemented in lisp or java! Well, you'd
better put something about that in your requirements. And what if this
person writes 500,000 lines of code? Well, you'd better put something
about code size in the design goals. And what if he produces a huge
monolithic mess of code? Well, then put something about modularity in
the requirements doc, etc. etc.

The requirements and design goals document is done when you are
reasonably certain that you and the entire target audience would be
happy with *any* implementation, as long as it meets the documented
requirements and design goals.

If you've done this, you've defined the true parameters for the software
development effort. The solution can be as creative, innovative or
unusual as the designer wishes, as long as these requirements and design
goals are met.

Choosing an Implementation
==========================

Now comes time to choose an implementation. To get the best possible
implementation, you want to consider the widest number of options that
meet your requirements. Put everything on the table. Have users write up
proposals, suggest ideas. You can either work on a community-developed
implementation document -- or even better -- have a design competition.
You want to get as many creative approaches submitted for consideration
as humanly possible.

The general approach I suggest is:

1) Allow open submission of implementation proposals from the public
(just a proposal, no code) Everyone, including managers, me and "Joe
User" are allowed and encouraged to participate.

2) Post these to gentoo.org, along with commentary from Gentoo design
leads/managers (what I liked, what I didn't like.)

3) Have a prototype design competition. The designs then have an
opportunity to take into account Gentoo feedback from step #2.
Group X can also incorporate ideas from Group Y's original proposal,
etc. You may or may not require code to be submitted, depending on the
scope of the effort. Everyone, including managers, me and "Joe User" are
allowed to submit prototype designs.

4) Choose a prototype implementation. This would be done by manager vote
or by whoever is leading the development effort if it is contained
within a single project. Then develop the production version in-house
and use any prototype code as a basis for the production version. You
could in theory choose 2 prototypes and merge the code to produce the
production version, or choose mostly one prototype and with various
features from some of the other prototypes, or just use a single
prototype as the basis for the implementation.

Spies and the Definition of Real Success
========================================

We had an interesting incident take place with portage-ng development.
Pieter noticed that hours after he posted ideas to the
gentoo-portage-dev mailing list, they would show up in a Zynot
developer's design doc for Xeta, the Zynot package manager. This made
Pieter wonder -- by having an open process like this, are we simply
giving away our great ideas to our competitors? And because of this,
what is the point of having an open design process?

My answer is that it doesn't matter that Zynot is copying us. Assume
that Zynot takes all our good ideas for portage-ng and incorporates them
into their design document for Xeta. Now, let's assume that they
successfully execute on their design, and their result is *10% better*
than portage-ng.

Now, the question is, will anyone use Xeta. The answer: probably not.
They'll use portage-ng because they were personally invested and
involved in the development of it. They were able to review the entire
design and development process, submit proposals and prototype
implementations, and thus have a very good understanding of what
portage-ng is and that it is good. They know that it meets their
requirements, which were carefully documented at the beginning. And
because we made sure we had a thorough set of community requirements,
and made sure that we satisfied their requirements with portage-ng, the
cool extra Zynot stuff isn't very relevant to them. These cool features
can be added to portage-ng 1.1 -- if they are important enough for our
users.

The point here is that there are different definitions of success, and
ultimately the key one is to be responsive to our users and ensure we're
meeting all their requirements, and develop things openly will full
peer-review so that they *know* we are meeting all their requirements.

Maximum PR Impact for Gentoo
============================

Here is another key aspect to success -- we need to tell the world about
our progress. If a design doc is updated, we need to post a news item
about the new stuff on gentoo.org. This news should end up in GWN.
That's why XML is so important. An official document means a lot more to
users than a mailing list thread because it's much more
"official-looking."

Let's focus on our competition again, which Zynot likes to think they
are (at least they seem to be almost predatorially targetting us.) They
are trying to create the ultimate package manager, and dethrone Portage
and thus Gentoo. That way, Zynot can become the new hot distribution.

Here's the problem with their strategy. Our strength is not Portage, but
our community. They think they will "win" by unveiling a hot new package
manager, and people will be so impressed by its technical prowess that
they will switch to Zynot. There's nothing we can do from stopping them
from releasing a well-designed package manager.

But we can still win the battle -- the battle is really ours to lose.
When our portage-ng design doc is updated, we're going to publicize it.
We're going to tell the world about the requirements and design goals of
portage-ng on a regular basis. We're going to regularly give people
updates on portage-ng, request they share their requirements with us,
and show them that we care about their needs. By doing so, we're going
to win the package manager battle during the design phase, by clearly
demonstrating that the design of portage-ng is centered around *them*.
This will impress the socks off our users and show them that we're
serious about making sure that Gentoo is the best possible solution for
them.

Likewise, I think there exists similar potential for Gentoo to win the
"ready for business" battle in the design phase. I think that the
"stable tree" issue needs to be addressed in a way that will get us from
today to the point where portage-ng is rolled out. The reason for this
is that we're now at the point where we're a contender for production
deployment. The future potential for Gentoo is going to be defined by
how appropriate we are for production systems. That will at least be
true until portage-ng debuts.

Anyway, that's about all I can write in one day; I hope that it's
helpful.

Regards,

Daniel


--
gentoo-managers@gentoo.org mailing list


--=-vGGsMI5mjLq/3omZJrik--