Gathering volunteers for development tool

[lastcraft]

Hi.

The project is up. Please send me your Sourceforge usernames by e-mail if you haven't already done so. Not the ID number, but the name. I got this wrong last time.

Even if you just want to be a tester I'd rather add you to the project. It means I can make the developers mail list private if needed.

yours, Marcus

[lastcraft]

Hi...

The most basic thing you can do is write a word document. Usually you have a standard template to write your document, and that's really only so you remember to address all the important areas: install/upgrade, backwards compatibility, performance/capacity, init and recovery, security, maintenance/servicing, reporting/auditing, etc.

So supplying standard templates could be a future feature then. Hm...

Most often you need numbered requirements, usually coupled with a scenario - and even better, an architecture description. As soon as you get numbered requirements, it's easy to put them in a list and relate them to other deliverables of a project.

Perhaps not numbered, but at least traceable by the machine. Ultimately such a tool would develop into a document manager and project managment tool. Right now it's still experimental, but we need the traceability to tie the test results up to the original document. Thehighest level of features that I would commit to on a version 1 is the ability to export the data to M$ project or some such.

Also, requirements usually get tagged with a few attributes: release, status (accepted, or draft), source (who came up with it, or who wants this), and possibly other category type attributes.

They can probably be left inside the documents.

My bliss would be a system where you can take a requirement and trace it from requirement -> architecture description -> design [document section] -> code delivery -> test case, and get status on each link in the chain. So you can say, we have implemented 48% of the requirements, and have a 80% of the tests have passed.

Those last figures are the point really. The intermediates are fudge prone, and even RUP measures progress only by working code. This is all developer to manager communication. There is also the glossary aspect so that the developers can buy-in. The developers should be able to highlight a phrase just to raise it as an issue. The system can then report that a phrase needs definition and the development is held up awaiting this. The traffic has to be both ways.

So, you PHP guru you, fancy joining the project. At least as a tester?

yours, Marcus

[RossC0]

Just read about this from www.phplondon.org.

Please add me to your list - I'll gladly help out in anyway I can!

[lastcraft]

Hi...

I'll gladly help out in anyway I can!

Send me your Sourceforge username and I'll sign you up.

Once that happens you have a little catching up to do. You'll need to look at the BACKLOG and TODO files in the CVS repository and join the arbiter-devel mailing list. Announce yourself on the list, with an estimate of hours, and you're off.

yours, Marcus

[Big Fat Bob]

Yo

A wiki is a good start, but it would need some explicit ways to do traceability of requirements.

So what this boils down to is some form of search, though proberly more refined search criteria I think ?

[lastcraft]

Hi...

So what this boils down to is some form of search, though proberly more refined search criteria I think ?

I am hoping we won't end up building a complete document management solution . Hopefully the number of documents will be small, perhaps just one. I am guessing at something like...

class Repository {
    function findRequirementsByTitle($title) { }
    function updateRequirements($document) { }
    function findRequirementsByTest($test_name) { }
    function findRequirementsByGlossaryTerm($term) { }
} 

...for a first version. With a possible...

class Repository {
    ...
    function findRequirements($criteria) { }
} 

...later.

Is this what you mean?

yours, Marcus

[Big Fat Bob]

Yo

No

But I got the impression of search (or searchable) when NativeMind was talking about tracabilities, I've assumed that the repository would need to be searchable ?

Think I've picked things up back to front

[lastcraft]

Hi...

Anyone willing to donate any requirements documents? We would be checking them into SF CVS, so they need to be copyright free and massaged enough not to give away any secrets.

yours, Marcus

[escape164]

What size of a document are you looking for? I have a document that I wrote last weekend for a simple 5 page website with a 'Find a Store' type feature that I'd donate. Of course, I'll need some time to change the names to protect the innocent. :-)

Let me know and I'll email it to you.

[lastcraft]

Hi...

Let me know and I'll email it to you.

Yes please! It would be really nice to have stuff that is client written.

yours, Marcus

[escape164]

Oh, this isn't client written, sorry! I'll dig around and I might have an older copy of something that is. I'll post it here if I can massage it enough.

[lastcraft]

Hi...

Oh, this isn't client written, sorry! I'll dig around and I might have an older copy of something that is. I'll post it here if I can massage it enough.

Even developer written stuff is cool too. Really the more the merrier right now as otherwise the parsers will reflect the style of the developers rather than being battle tested.

yours, Marcus

[DmS]

Hi there marcus.
I'll do some digging to see if I have some req-specs that's possible to anonymize without being to systems specific (God knows I've written tons of them over the years...). Meanwhile, take a look here http://www.systemsguild.com/GuildSit.../Template.html to see if it's something that can be used.

It's copyrighted but free, I can't see anything about not beeing able to use it as input in a project like this so I guess it might be worth asking them if it's ok.
It's a very detailed template for developers, but parts of it can be used with client interaction as well.

And here http://www.gurusnetwork.com/tutorial/wbtgd/3/ you can see the headlines from that template that I try to use as much as possible.

This is also an interesting app in the line of this project: http://satc.gsfc.nasa.gov/tools/arm/index.html It's a report generating tool for requirements.

And lastly an overview of some capabilities of different requirement management tools: http://www.paper-review.com/tools/rms/read.php

Hope you can find something useful in this.
Cheers/Dan

[lastcraft]

Hi...

Hope you can find something useful in this.

Certainly have. I have asked to use the template as a test sample and am taking a look at ARM. Very interesting.

yours, Marcus

[maetl]

Hi Marcus,
This idea looks really interesting, but I now have a few process/methodology related questions bubbling in my head that I was hoping you could help clarify...

1) What exactly do you mean by a problem domain - how granular is it? does it go down to the level of specific business rules, organization dependent processes, or is it more general, dealing with processes common to any organizations in a particular business sector...

2) What happens to the role of designer on these kinds of projects? I'm assuming the kind of apps you are talking about building/generating with this process would be heavily transactional, with lots of user input and interaction, so would benefit greatly from a direct mapping of test cases to requirements. But building a successful software product isn't just about meeting requirements (or is it?) - what about the immeasurable qualities of structure/shape/personality, the irrational things that make an interface feel 'right' to users... I get the impression from what you are suggesting that the qualities of the whole are emergent from the underlying process, and are not necessarily shaped or defined at a high level.... Is there any reason why information architecture and design approaches are 'wrong' from this perspective? Are they incompatible paradigms?

3) I thought use cases were not really about 'click here' or 'go here' - more about defining high level tasks that the system has to accomplish, and trying to find the most appropriate naming/abstractions to describe the functionality of a system. Potentially, they could be used as preparation for more structured versions of requirements. From experience, I see that there is no singlular answer here... Some people are just far more comfortable with excel files, others more comfortable with a visual/diagramatic representation... is there any relationship to UML conventions in the model that you are proposing, or is that out the door... Just wondering, as I think there are good and bad things about UML, and you seem to have answered some of these problems very succinctly with your strategy here...

- Mark

[maetl]

sorry, just discovered some of the other messages here that I missed on that first sweep, and after looking at the UML diagram of the repository, its starting to sink in...

You can trust a designer not to want to control chaos

But it's amazing how fast good ideas pick up momentum... great stuff!

[lastcraft]

Hi...

Your coments come from a different angle, so I thought I'd take the liberty to reply line by line...

1) What exactly do you mean by a problem domain - how granular is it? does it go down to the level of specific business rules, organization dependent processes, or is it more general, dealing with processes common to any organizations in a particular business sector...

I am only thinking of small web projects of the type tackled by small web development shops for external clients. This narrow focus has a few advangtages (see below). The problem is hard enough as it is, without going for a general solution .

2) What happens to the role of designer on these kinds of projects?

This would run parallel to it. Sections of the requirements that dealt with usability or visual design would have to have other constraints applied. I simply don't know enough about these processes to even comment, let alone start designing a tool.

The main thing is that the original document is preserved, so this tool adds progress information without taking anything away. Hm...it could have a plug-in architecture though.

I'm assuming the kind of apps you are talking about building/generating with this process would be heavily transactional, with lots of user input and interaction, so would benefit greatly from a direct mapping of test cases to requirements.

Yes. These parts of the systems are expensive to change when you get them wrong though and often have to be visually inspected by both client and developer.

what about the immeasurable qualities of structure/shape/personality, the irrational things that make an interface feel 'right' to users...

Well, because the developers will have the raw project goals blended right there with test examples, I am hoping that the project vision will be communicated to the developers far more effectively.

I don't know how to measure "progress" on user interface issues, although someone mentioned a scoring system. It might be possible to have some module that inserted some usability statistics into a use case as well, but that would be in the future.

I get the impression from what you are suggesting that the qualities of the whole are emergent from the underlying process, and are not necessarily shaped or defined at a high level....

I think an iterative process is essential. I think clients should bring to the table the mission statements of their project. Bringing detailed expectations can be positively harmful. The idea of teh tool is that it should make progressive refinements easier. It makes the requirements document a live document and the central focus of the project.

I hope.

Is there any reason why information architecture and design approaches are 'wrong' from this perspective? Are they incompatible paradigms?

At a personal level I am disenchanted with them and feel the most successful projects are evolutionary, rather than some grand vision. That's a personal direction though and not in-built into the tool. If you want a big up-front requirements doc. with lot's of UML as well as tests that's fine too. It's main role is measuring progress and aiding project sign off.

3) I thought use cases were not really about 'click here' or 'go here' - more about defining high level tasks that the system has to accomplish, and trying to find the most appropriate naming/abstractions to describe the functionality of a system. Potentially, they could be used as preparation for more structured versions of requirements.

This is the big example I alluded to earlier of targeting small web apps. Every client these days understands a web browser and can express themselves in these terms. If you want to say categorically what will happen in a particular situation then a click sequence will resolve it for sure. Removes later disputes.

Ok, really you want to talk in higher terms in practice. That's why the "macro" feature is so important. Clients often understand Word macros and so I think this metaphor is valid.

Some people are just far more comfortable with excel files, others more comfortable with a visual/diagramatic representation... is there any relationship to UML conventions in the model that you are proposing, or is that out the door...

I have only ever encountered one client that communicated their intent with UML. I think I was lucky to get even this one. Like it or lump it, requirements always seem to arrive in word processor format.

There are tools being written to cope with Excel spreadsheets, and Fitnesse uses this format. This to me seems more appropriate for larger projects for financial institutions. Anyway, why repeat what others are doing? Although very much experimental, I think it is closer to small web development culture.

Hence recruiting from Sitepoint...

Just wondering, as I think there are good and bad things about UML, and you seem to have answered some of these problems very succinctly with your strategy here...

I am not stopping UML, but it would be just a visual artifact as part of the document. No attempt would be made to implement an MDA solution.

yours, Marcus

[NativeMind]

I can't provide an example requirements document, but here's an outline of areas that are usually addressed:

1. Introduction - what is it we're building here?
1.1 Background information - any background information needed to understand
1.3 related stuff

2.0 architectures and requirements
2.1 high level overview
2.2 configuration - also backwards compatibility, notes on third party software used, etc
2.3 functional requirements/architecture (big section)

Additional areas addressed in 2.3 or as subsections:
- Performance/Capacity
- Security
- Reliability and Availability (how reliable is this thing? what happens if there is an error, what are the use cases)
- internationalization (if necessary)
- Usability
- Maintenance (stuff like logging, diagnostics, etc)
- Error Reporting - what happens when there is an error, something serious that may need human intervention. Does it generate SNMP traps, send an email, etc
- Installation/Upgrade
- Backup/Restore

Of course, all of those areas depend on what your building and how detailed of requirements you want/need. You can also break down each of those sub-topics into further sub-topics of things you usually address. E.g .for security you would probably talk about transport encryption (HTTPS), authorization/authentication, password features, database security, preventing against certain attacks (XSS, CSRF, SQL injection, etc).

When working with partners, I've had the opportunity to see what some other large companies do for requirements. The actual document structures and content tend to vary in terms of both layout and typical areas they address explicitly. For example, the link above has a 'theme' to it where it addresses the customer impact, use case, and requirement in every section. If the customer request is vague, then you may not have a 1:1 relationship on customer impact statement to requirement. In those cases, your requirements may just talk about what functionality is being provided and what the expected use case of that functionality is.

Btw, I think a document management system is going to be inevitable. At least in some sense. After all, you need to be able to track versions of the document. So in version 1, we agree to these requirements. People print out that version, use it for development, share it with sales, etc. Next month you change your mind and you change some requirements, i.e. changing functionality of the system. You need to be able to track this change, but the fact that the document changed (document versioning) as well as a change control system for the document.

Most change control systems are similar to source control systems in that you create a modification request (MR) in the system. This MR states the requested change and some reasoning behind it. Then an MR system notifies all people necessary of the change, giving a chance for people to review it. Then when you update the document, you specify which MRs were encorporated into the new version.

Document control and MR management is probably not at the core of the desired features in this application but sooner or later it'll need to be addressed if this tool is to be successful for use by groups of people.

[Andy Tomaka]

You're definitely building a keeper here Marcus.

WebDAV does seem like a possibility. They've got a solid FAQ up at http://www.webdav.org/other/faq.html I really haven't messed with it too much, but it seems impressive at first glance.

[lastcraft]

Hi...

I can't provide an example requirements document, but here's an outline of areas that are usually addressed:

Really it's nice messy hand written documents with lot's of irrelevant mark up that we need. Document parsing and modification is at the core of the problem.

Document control and MR management is probably not at the core of the desired features in this application but sooner or later it'll need to be addressed if this tool is to be successful for use by groups of people.

Yes. I am trying to keep the back-end flexible enough that we can interface with document managment systems if needed. That's for the future though. Got to get our first data point up to make sure that the whole thing is worthwhile.

yours, Marcus

[maetl]

Sections of the requirements that dealt with usability or visual design would have to have other constraints applied. I simply don't know enough about these processes to even comment, let alone start designing a tool.

I have noticed that what is meant by 'requirements' can take on a very different meaning across different small-medium sized web projects... Maybe it has a more fixed meaning in enterprise application architecture circles?

I have seen documents that range from being basically a high level statement of concept / creative brief, to documents resembling a low level functional spec / use cases, and all with the name 'requirements' stamped out in big letters on the cover page.

The main thing is that the original document is preserved, so this tool adds progress information without taking anything away.

This makes me think of being able to generate 'compound' documents too, building a higher level picture from requirements fragments and granular little parts of the puzzle...

Well, because the developers will have the raw project goals blended right there with test examples, I am hoping that the project vision will be communicated to the developers far more effectively.

Sort of like 'live' use cases, or user stories... I like the idea of the testing process feeding back into the document itself, that is where the value is. I have heard a lot of talk about the 'Project Plan' or 'Design Document' being an evolving document throughout the process, but 99 times out of 100 this kind of iteration never happens, I wonder if that kind of evolution is even possible without involving tools like the one we are discussing here...

I don't know how to measure "progress" on user interface issues, although someone mentioned a scoring system. It might be possible to have some module that inserted some usability statistics into a use case as well, but that would be in the future.

From my experience, usability is quite a 'fuzzy' field. A lot of it is based on participant observation, and recording the kinds of responses that are difficult to quantify, but useful for designers and IA's to understand the subtleties of a navigation schema and the kinds of behaviour that it encourages. The guiding method of usability testing is to focus on 'goals', rather than 'tasks' as use cases or user stories do. Users often percieve identical steps to complete a task in very different ways, depending on the context of the UI design, typographic heirachy, tone of content etc...

There is no simple answer to how usability can live happily together with more developer centric processes. I do think that both the usability and agile communities will start to see more and more that they have many goals in common, and I would hope that cross pollination can only make both fields stronger...

At a personal level I am disenchanted with [those approaches] and feel the most successful projects are evolutionary, rather than some grand vision.

If only I was better at convincing clients (and sometimes designers and project managers too) of this... I do think that information architecture is more than just making sitemaps and up front design though, and that the ideas of the Christopher Alexander's and Stewart Brand's of this world are just as relevant to IA design as they are to OO programming... The waterfall / top down approach to software dvelopment has a lot of parallels to the large scale mistakes made by modernist architects like Le Corbussier in the mid 20th century, and a lot of architectural theory has risen to (presumably) correct this imbalance... its funny that these ideas have ended up being taken a lot more seriously by programmers than by architects or urban planners though...

Every client these days understands a web browser and can express themselves in these terms. If you want to say categorically what will happen in a particular situation then a click sequence will resolve it for sure.

Yes, that is very important...

To take things in the opposite direction, I notice from presenting aspects of a solution design in diagram/schematic form, that it always involves a huge amount of verbal explanation, demonstrating the detail, and this takes a lot of effort on top of the effort required to produce the deliverable itself, and even then, I sometimes don't know if they actually understood it or not. I would never expect a client or even a developer or a visual designer to necessarily be able to pick up one of these stacks of paper and just naturally read the features and elements involved and understand them. Clients especially find this very hard, as they are placed in the difficult position of having to both make directive decisions to confirm a particular approach, yet they also want to rely on the guidance and judgement of the designer in terms of the knowing what the right approach is...

On the one hand, I think the social collaboration and communication that diagrams provide is extremely important and there is a lot of value in that alone, but on the other, if it is possible to be unambiguous and communicate intent directly in the browser, I am all for it, because after all, that is where the action is at...

[lastcraft]

Hi...

This makes me think of being able to generate 'compound' documents too, building a higher level picture from requirements fragments and granular little parts of the puzzle...

Project metrics would be a good source of continual buy in from the different parties. If it is to become the centre of the development process then it has to be fun as well...

Sort of like 'live' use cases, or user stories...

Exactly. Wish I'd called it "LiveStory" now . So, you going to sign up ?

yours, Marcus

[josheli]

one observation.... why try to parse unknown document structures? that's going to get real woolly. i don't think it would be too much to ask to have a document structure users have to adhere to. as simple and constraint-free as possible of course, but you're already asking them to bold and bullet and list expectations... why not give them fairly clear guidelines? i think you'll end up doing that anyway. "sorry mr. user, we missed that requirement because there was a stray comma and two newlines...."

one benefit you get from this is that it's sometimes possible to parse Word docs with Regex if you know the pre-defined structure beforehand.

also, fyi....

a few months back, i dabbled in creating a Word parser/generator. the best (only?) documentation or Office binary file formats i found was here:
http://user.cs.tu-berlin.de/~schwartz/pmh/
and especially:
http://user.cs.tu-berlin.de/~schwartz/pmh/guide.html

but it's 7 years old, not for the faint of heart, and only covers up to Word 6 (fortunately MS likes to be BC). it is the basis, however, for Perl's Spreadsheet::WriteExcel and Spreadsheet::ParseExcel modules, and thus PHP's Spreadsheet::WriteExcel module. speaking of that, it is built on the pear OLE package, which contains some code to read portions of binary office documents. might come in handy.

there's also a Java Excel read/write API based on the "Laola" research mentioned above. i started porting it to PHP, but like everything else, found an easier way and lost interest when i had no personal stake.

another angle i've been dabbling in is to create a COM socket server, so on the remote *nix machine you could do stuff like:

$com = new RemoteCom('192.34.55.150');
$doc = $com->loadWordDocument('req.doc');
echo $doc->wordCount;
$html = $doc->saveToHtml(); 

say, my enterprise uses WordPerfect, thus i've written a WordPerfect parser/generator, but that doesn't help much, does it?

can you tell i have an interest in PHP-Office integration?

[[MaDMaX]]

What if you created a Thunderbird plugin: "Send to Tool" and instead of worrying about html, you just grab the plain text of the email?

[lastcraft]

Hi...

What if you created a Thunderbird plugin: "Send to Tool" and instead of worrying about html, you just grab the plain text of the email?

Because that's not how requirements docs. are written. We have to go with the situation as it is rather than as we would like it. Buy in is going to be the biggest hurdle.

@Joshelli:

Cheers for the links, and I'll follow them up. As for the degree is robustness in the parsing spec., that has yet to be worked out. We won't know until real users try it.

yours, Marcus