search

itc-wgtools / cPP-Tools

A repository for the creation of templates and guidance to be shared by all iTCs for the creation of cPPs and supporting documentation.
https://itc-wgtools.github.io/
6 stars 3 forks source link

iTC Templates #23

Open ansukert opened 5 years ago

ansukert commented 5 years ago

Something occurred to me as I was looking at Issue #22. The following is completely a suggestion and not a criticism in any way.

Anyway, as I was thinking of templates I did a real quick scan of the cPP template and something came to mind that I did ~35 years ago when I was working for GE in Software QA. Just to put this in some context, we were developing a very large radar system for the Air Force and we were in the requirements development phase. We had submitted a large set of B-Specs (that's the DoD designation for a requirements spec) and the Air Force was very unhappy with the quality of the specs we had submitted. Eventually it was decided that part of the problem was that the engineers developing the specs were new and really didn't know what should go into a B-Spec outside of the DoD standard which of course didn't provide much direction.

Anyway, the idea I helped come up with was to develop a B-Spec Style Guide for developing a B-Spec that we could give to the spec developers. The guide had two parts- the first was general word guidance on what should go in each B-Spec section that expanded on what was in the DoD standard (this is essentially what is in the templates we are creating).

However, it is the second part that is my suggestion. In each section we put in a sample of text from an actual B-Spec that provided a good sample of what should go in that section. I think we should do the same thing with our templates - for each section include a sample for an actual iTC document to give someone an idea of not just what goes in that section but how it might be worded. In the GE case it completely turned around the quality of the B-Specs we provided and made the Air Force very happy. It might serve the same purpose for iTC newbies like we will be in the Hardcopy iTC once it is formed.

Think about it.

woodbe commented 5 years ago

I really like this idea. I had somewhat gone in the direction of no examples to keep the documents somewhat clean. For the moment I have created a new Milestone called Phase 3 which is targeted to after the full release of docs at the ICCC this year. That said, I'm for pulling this in if we can make it work, so right now Phase 3 is more like a parking lot.

I think the biggest question would be where should we pull examples from. I don't think we should write them ourselves but that we should pull examples from existing documents.

I definitely think this is useful, but one question would be whether this should be included in the template directly or maybe referenced somewhere else (for example on a separate web page under the one I posted the draft on) that contains several examples of different types, SFRs and evaluation activities associated with them (i.e. cPP and SD parts for a requirement).

We had talked about in the future of collecting all the Assumptions, Objectives, etc into one place so you could pull them out, so I think this falls along those lines, so maybe the question is where to put these things. I don't think they should all be in the templates, but maybe some should be there and some should be on a web page, but I don't know.

@ansukert do you have any thoughts about that? I completely agree that examples make things better, so do what do you think about placement?

ansukert commented 5 years ago

Brian,

Maybe at the Singapore Workshop I’ll tell you how I stumbled on this suggestion.

Getting back to your comments, I think as long as newbies like me know where to go to see the samples, it really doesn’t matter whether the samples are in the template or on a separate web page. Are think there are pros and cons to both approaches:

In the Template

Separate Web Page

Maybe as you said the solution is some of both; the trick will be determining what goes in the template and what goes in the separate document. The other trick, as you said, will be figuring out what actual wording you take from what iTC’s documents for each section. But the Tools WG has members who have been involved with multiple iTCs so we should have a good idea of where to start here.

I am just glad my “corporate memory” may actually be of value here.

Alan

From: Brian Wood notifications@github.com Sent: Wednesday, June 19, 2019 3:34 PM To: itc-wgtools/cPP-Tools cPP-Tools@noreply.github.com Cc: Sukert, Alan Alan.Sukert@xerox.com; Mention mention@noreply.github.com Subject: Re: [itc-wgtools/cPP-Tools] iTC Templates (#23)

I really like this idea. I had somewhat gone in the direction of no examples to keep the documents somewhat clean. For the moment I have created a new Milestone called Phase 3 which is targeted to after the full release of docs at the ICCC this year. That said, I'm for pulling this in if we can make it work, so right now Phase 3 is more like a parking lot.

I think the biggest question would be where should we pull examples from. I don't think we should write them ourselves but that we should pull examples from existing documents.

I definitely think this is useful, but one question would be whether this should be included in the template directly or maybe referenced somewhere else (for example on a separate web page under the one I posted the draft on) that contains several examples of different types, SFRs and evaluation activities associated with them (i.e. cPP and SD parts for a requirement).

We had talked about in the future of collecting all the Assumptions, Objectives, etc into one place so you could pull them out, so I think this falls along those lines, so maybe the question is where to put these things. I don't think they should all be in the templates, but maybe some should be there and some should be on a web page, but I don't know.

@ansukerthttps://github.com/ansukert do you have any thoughts about that? I completely agree that examples make things better, so do what do you think about placement?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/itc-wgtools/cPP-Tools/issues/23?email_source=notifications&email_token=AMA5L5XV7C5GB4W4R7JHIDDP3KC2PA5CNFSM4HZMNKN2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODYDBTCI#issuecomment-503716233, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AMA5L5VOANKR76ZJHHEISBLP3KC2PANCNFSM4HZMNKNQ.

The-Fiona commented 5 years ago

This is a great discussion. In my opinion it would be better to keep the templates as simple and clean as possible, so that PP editors/TCs/iTCs can use them as simply as possible. As an editor the first thing I would likely do is strip out any examples and other stuff so that I had a clean start and there was little danger of inadvertently leaving example-text in the "real" document.

Having said that, the examples and help described above will be invaluable. Although I will say that I often experience a tendency for folks to (mis)interpret examples as "law", and not use the flexibility that it due to them: It's some kind of a psychological thing..

Yes, a separate document/template would work. Or, perhaps we can eventually develop just one document that includes the examples, but that we can process to also generate the clean template. So we would end up with something like "template_with_examples" and "template_clean" without too much work.

On the SPD-elements (assumptions, threats, OSPs). As a user of many PPs, PP-Modules and STs I couldn't agree more that the TCs and iTs would benefit from some database of what has been used before. This is perhaps especially useful in the case where PP-Configurations are being specified, and the union SPD is pertinent. Some recent work I did really highlighted that problem to me. We often have SPD-elements with the same name, but very different words. While these differences are very carefully thought out by the TCs, It would be good for them I think to have the reference of what has gone before.

-Fiona

woodbe commented 3 years ago

To recap the call on 4/20:

Instead of trying to create examples, we will provide guidance along the following lines:

From this info, we will build some sort of guidance to assist in the SFR creation (and especially for EAs), to look at what others have done before, based on broad categories.