cpp-netlib-devel

[cpp-netlib-devel] [wiki] Updates to SoftwareSpecifications and MessageRequirements

[Dean M. B. <mik...@gm...>]

Hi Guys,

I've made a few changes to the SoftwareSpecifications page and
following John's structure for the page. I keep forgetting that you
can have more than one page on a Wiki to put information in. ;)

Anyway, I also made a new page where the MessageRequirements are put.
However, note that this doesn't follow the same format that the
HTTPAPIRequirements page proposes. I have yet to flesh out the other
requirements pages, and I think these pages ought to be filled out by
"users" of the library (or at least representative users). For one, I
think I need to move the contents of MessageRequirements to
MessageDesignSpecifications looking at the content of that page...

What do you think guys? Comments would be most appreciated. :)

-- 
Dean Michael Berris
blog.cplusplus-soup.com | twitter.com/mikhailberis
linkedin.com/in/mikhailberis | facebook.com/dean.berris | deanberris.com

Re: [cpp-netlib-devel] [wiki] Updates to SoftwareSpecifications and MessageRequirements

[John P. F. <jf...@ov...>]

I hate to be stickler on this, but we should come to a consensus on the 
format. IEEE-830-1998 and IEEE-1016-1998 are industry standards. They 
are essentially lingua franca for nearly every developer that I've come 
across. From experience, I strongly feel that basic use of the concepts 
from 830, such as User Characteristics, Scope, Product Perspective, and 
Specific Requirements would be extremely beneficial for this project. I 
can't tell you how many times I've discovered overlooked aspects to 
something I was building by following those guidelines.

John

Dean Michael Berris wrote:
> Hi Guys,
>
> I've made a few changes to the SoftwareSpecifications page and
> following John's structure for the page. I keep forgetting that you
> can have more than one page on a Wiki to put information in. ;)
>
> Anyway, I also made a new page where the MessageRequirements are put.
> However, note that this doesn't follow the same format that the
> HTTPAPIRequirements page proposes. I have yet to flesh out the other
> requirements pages, and I think these pages ought to be filled out by
> "users" of the library (or at least representative users). For one, I
> think I need to move the contents of MessageRequirements to
> MessageDesignSpecifications looking at the content of that page...
>
> What do you think guys? Comments would be most appreciated. :)
>
>   

Re: [cpp-netlib-devel] [wiki] Updates to SoftwareSpecifications and MessageRequirements

[Dean M. B. <mik...@gm...>]

Hi John,

On Sat, Aug 22, 2009 at 7:57 AM, John P. Feltz<jf...@ov...> wrote:
> I hate to be stickler on this, but we should come to a consensus on the
> format.

Why?

> IEEE-830-1998 and IEEE-1016-1998 are industry standards.

I think this makes sense if you're writing an _application_. Besides,
I've worked on so many software projects that didn't have industry
standard specifications. FWIW, these software projects got done and
delivered without relying on heavy "formal" documentation. Of course
YMMV.

For an open source project, I think we remain as fluid as possible.

Or, you can fill out the specifications with whatever format you like
-- I'll follow your lead on it if it makes it easier for you to do
things easily.

At the minimum I can give what I'd like the interface to the clients
to be Boost-style: documenting the concepts, documenting the functions
I expect to see, etc.

(Also, I don't have access to the official PDFs of these standards
having only ever heard of them today).

> They
> are essentially lingua franca for nearly every developer that I've come
> across.

I think we're hanging out with different types of developers. ;)

I've been dealing with agile software development practices for the
past 5 years, and so far I have yet to encounter a single formal
software requirement document based on anything taught in my Computer
Science classes; and these solutions have been delivered on time
delivering the features required. Not that I wouldn't know what to do
with one, but I'm saying it rarely needs to be that formal nor
"complete" at the beginning. Maybe if you're used to the "waterfall"
model, then you'd feel that the specifications would be required from
the beginning. I OTOH am not used to the waterfall model, and would
rather deliver according to what interface I intend the client to look
like while it's being used -- underneath, we can "wing it" and just
deliver what we feel would make sense.

Then, we release early, and release often -- or at least should do so.
We iterate. We can keep changing the implementation and the design and
everything but keep the client interface constant -- and that's all
there is to it. It's alright if we make mistakes and release something
that's broken, we'll just fix it in the next release.

Are you looking for just the client interface? Because right now, the
message::basic_message<> and http::basic_client<> interfaces are
pretty much going to be the same until 1.0 comes out. Code does the
talking. The tests are the requirements. New requirements mean new
tests. I can keep writing new tests and stop implementing too, but I
don't think that's a good use of my time. ;)

> From experience, I strongly feel that basic use of the concepts
> from 830, such as User Characteristics, Scope, Product Perspective, and
> Specific Requirements would be extremely beneficial for this project. I
> can't tell you how many times I've discovered overlooked aspects to
> something I was building by following those guidelines.
>

Sure, that's all fine and good if you're outsourcing work for a
product to be shipped and shrink-wrapped and never going to be
upgraded -- maybe if you're going to flash them onto devices, then you
really only have one chance at putting it in there. Requirements make
sense for these types of projects where you're meant to deliver just
one thing that would be required as it is (nuts, bolts, network
interfaces, realtime operating systems on non-reflashable ROM,
firmware on non-reflashable ROM, etc.).

I think drawing a line in the sand on the specification format isn't
something we should be doing -- but rather, let's put what you think
should be there and let's see how that works. Whether it's
industry-standard compliant documentation rarely means anything IMO
especially if it's the code that actually matters.

If you feel strongly enough about it, re-write it in the format you
want and I'll fill in the missing details that you want me to fill in.
(I should really subscribe to Wiki updates to these pages...)

HTH

-- 
Dean Michael Berris
blog.cplusplus-soup.com | twitter.com/mikhailberis
linkedin.com/in/mikhailberis | facebook.com/dean.berris | deanberris.com

Re: [cpp-netlib-devel] [wiki] Updates to SoftwareSpecifications and MessageRequirements

[John P. F. <jf...@ov...>]

Dean Michael Berris wrote:
> If you feel strongly enough about it, re-write it in the format you
> want and I'll fill in the missing details that you want me to fill in.
>   
Fair enough. I'll rewrite what I can.
John