Requirements Elicitation starting 8/12/2020

[hamishmb]

Thanks, all fixed and attached. I have followed the convention of a page break before a major new section.

I don't think my tutor would be as concerned with the presentation as with the content of the document, but nevertheless, it's good for it to be polished.

[TerryJC]

You are probably right and he probably wouldn't say anything, but he might take it into account when he awards marks (assuming that's what he does).

[hamishmb]

Yeah, absolutely, I'm very appreciative of the feedback

[Penri]

Hello

It all reads well, the only thing I would suggest you change is reference to the Water Wheel in 2.1.1 and illustration 1, the item was removed because of the potentially detrimental effect it had on amphibians living in the river.

At some point I'd like to find a way of measuring water flow in the river without posing any danger to wildlife.

Penri

[hamishmb]

Good point, I must have missed that.

Are you sure you want to entirely remove all reference to it, just in case a design is later invented which avoids the problems of the previous water wheel?

[PatrickW]

Looks OK to me.

My Dad saw the front cover and thought it should have an author stated. I quite like to see an author stated, too, but I'm not sure that is in keeping with our other documents.

My Dad also thought it should have a document number. But, of course, we haven't got a document numbering system, so it would not make sense to make an exception. A name is broadly equivalent to a number in this context; just a bit less concise.

Some nitpicks, queries and corrections:

License:
The Creative Commons license indicated on the front cover is different from the one referenced in 1.2 Related Documents. On the cover it is CC BY-NC-SA 4.0, but in the references it is CC BY-SA 4.0.

On page 4:
First paragraph:
I read "Additionally, as a subsidiary function" to mean "In addition to the two distinct functions already mentioned." Took me a moment to realise that, no, the additional function is actually not additional at all. Rather, it is one of the two already mentioned. I'd probably go for something like:
"The GUI has two distinct functions. Primarily, it is to allow visitors [...] River feature. As a subsidiary function, this GUI..."

"For Visitors" bullets:
Flow rate is mentioned here, implying water wheel or similar. Do we want to keep this? (I realise this isn't part of the requirements, so it might be kept as context.)

Third-to-last paragraph, which begins "Data will be generated":
This paragraph talks about a Master Pi making data available to the Visitor GUI, which I believe is out-of-date, and contradicts the description in 3.2.2 Methodology.

Open University Project
If this is going to be a document held by WMT, then I feel as though it ought to briefly introduce the fact you (Hamish) are doing an Open University Project to produce the mobile visitor GUI. The meaning of "Open University Project" is only clear to me because I already know that.

2.1.1 Main River Circulation:
"Figure 1" is referenced, but in the annex it is listed as "Illustration 1". I like to use LibreOffice's cross-referencing feature for these kinds of references. That way, if the figure's number changes, the reference will still name the correct figure.

"Sump Pump" in the text is "River Pump" in the figure. Confusing if you don't already know the system.

"Water Wheel" is mentioned, but not present in reality.

It's not clear why the diagram shows the system as of December 2017, rather than February 2021. I know that a diagram for that date already existed, but, if I didn't, I might assume it was created just for this document, in which case it would be bit odd.

The text goes on to mention Wendy butts, Stage butts, Hanham butts and Gazebo, but only the Wendy butts are shown on the diagram, and are not labelled with the term "Wendy". (Because the diagram pre-dates the other butts, but, again, the reader may not know this and is left to figure it out.)

If you aren't going to update the diagram, I would suggest briefly mentioning that the system now includes more butts groups than are shown on the diagram.

2.1.2 Water Collection:
"Figure 2" is referenced, but in the annex it is listed as "Illustration 2".

In Figure 2, we do have more butts shown, but again they don't match the names in the text, because the system has evolved beyond the diagram. Railway Room Butts farm?

3.1.1 Visitor and Staff GUIs:
It's noted that Python is preferred because it has been used in the other elements of the system. Is it worth noting in addition, or instead, the reasons why Python was chosen for those other system elements? (Or referencing the fact that the reasons are documented elsewhere?)

3.2.2 Methodology:
As mentioned above, the description here contradicts the description on page 4.

In the second paragraph, I'm not sure that communicating via the web application server necessarily "improves" security, but rather provides what ought to be considered a minimum standard of security. I might therefore write "provides" rather than "improves".

Page 13, just above 4.2 Software Requirements for the Staff Display:
The term "stretch targets" is used without definition. Is this a generally understood term that does not require definition, or does it need to be defined?

To me it denotes a "nice to have" requirement, which does not have to be fulfilled in order for the project to be regarded as a success, but should be fulfilled if time allows, after all the non-stretch targets are met.

5.1 Operational:
It might be nice to apply some formatting to distinguish which rows in the requirements tables do not apply to the Open University Project. I'd probably do this to all the tables, for consistency.

5.1.3:
The term "the Site-local Pi" does not seem to have been defined anywhere, and I'm not sure what is meant by it. What is the Site-local Pi?

5.1.4, 5.1.5:
Just to confirm: these requirements are being excluded from the Open University Project? I have no objection to them being excluded, but I don't remeber it being discussed, so just checking to make sure it's not a mistake.

Annex A, Illustration 1:
This diagram could do with a legend or key to the symbols used.

To the uninitiated, it would be hard to identify the sump, because it is not labelled "sump". I already knew roughly where to look for it, and I still had to think about it for a bit!

As mentioned above, Illustration 1 has been referenced as Figure 1 in 2.1.1.

Annex A, Illustration 2:
As mentioned above, Illustration 1 has been referenced as Figure 2 in 2.1.2.

[hamishmb]

Thank you for the feedback Patrick.

I don't wish to modify the diagrams, as I am not able to do so easily and it would take time away from other preparation activities. As Penri said, I should remove the references to the water wheel and accompany illustration anyway

As for everything else, I shall provide an updated document that covers these points, and answer the remaining ones that I haven't changed here.

Important: License Query

Licensing-wise, I'll need confirmation of what the license is meant to be. IIRC, we wanted it to be noncommercial. Penri and Terry, what was your intention when you wrote the earlier versions of this document? This is the most critical deficiency you have identified, I think, Patrick.

I will ensure I cite all of your comments if I have to provide details for what was changed and why in the revisions to the document.

[TerryJC]

Looks OK to me.

Says he, before providing several screen-fulls of commentary.

My Dad saw the front cover and thought it should have an author stated. I quite like to see an author stated, too, but I'm not sure that is in keeping with our other documents.

My Dad also thought it should have a document number. But, of course, we haven't got a document numbering system, so it would not make sense to make an exception. A name is broadly equivalent to a number in this context; just a bit less concise.

Your Dad is quite right. In an engineering organisation there would be both. However, despite the fact that the number of Projects have expanded out of all proportion to the number when I produced the very first Requirements Spec, I still think that this is a bit OTT because:

• Authorship tends to be a collective thing and although I might produce the original first draft, the Released document usually contains contributions from everyone on the Project. I think out team is small enough for us to ask the right people the questions as they arise.
• Having a Numbering system would not really contribute much in this scenario and would add to the administrative load.

Penri,

As the 'other' ex-engineer, do you have any thoughts on this?

Patrick,

I'll leave Hamish to respomd to your 'nitpicks'.[/quote]

[hamishmb]

Okay, here are my changes and justifications.

Looks OK to me.

My Dad saw the front cover and thought it should have an author stated. I quite like to see an author stated, too, but I'm not sure that is in keeping with our other documents.

My Dad also thought it should have a document number. But, of course, we haven't got a document numbering system, so it would not make sense to make an exception. A name is broadly equivalent to a number in this context; just a bit less concise.

I think I agree with Terry's comments on this, but will wait for Penri to comment as well. I do not think this is relevant to the Open University, but can be added if desired.

Some nitpicks, queries and corrections:

License:
The Creative Commons license indicated on the front cover is different from the one referenced in 1.2 Related Documents. On the cover it is CC BY-NC-SA 4.0, but in the references it is CC BY-SA 4.0.

Amended in accordance with clarifications made over email - inclusion of noncommercial clause was the intention.

On page 4:
First paragraph:
I read "Additionally, as a subsidiary function" to mean "In addition to the two distinct functions already mentioned." Took me a moment to realise that, no, the additional function is actually not additional at all. Rather, it is one of the two already mentioned. I'd probably go for something like:
"The GUI has two distinct functions. Primarily, it is to allow visitors [...] River feature. As a subsidiary function, this GUI..."

Clarified previous sentence to avoid confusion.

"For Visitors" bullets:
Flow rate is mentioned here, implying water wheel or similar. Do we want to keep this? (I realise this isn't part of the requirements, so it might be kept as context.)

Acknowledged and removed.

Third-to-last paragraph, which begins "Data will be generated":
This paragraph talks about a Master Pi making data available to the Visitor GUI, which I believe is out-of-date, and contradicts the description in 3.2.2 Methodology.

Description updated to refer to database and NAS box.

Open University Project
If this is going to be a document held by WMT, then I feel as though it ought to briefly introduce the fact you (Hamish) are doing an Open University Project to produce the mobile visitor GUI. The meaning of "Open University Project" is only clear to me because I already know that.

Clarified and new heading created to draw attention.

2.1.1 Main River Circulation:
"Figure 1" is referenced, but in the annex it is listed as "Illustration 1". I like to use LibreOffice's cross-referencing feature for these kinds of references. That way, if the figure's number changes, the reference will still name the correct figure.

"Sump Pump" in the text is "River Pump" in the figure. Confusing if you don't already know the system.

"Water Wheel" is mentioned, but not present in reality.

It's not clear why the diagram shows the system as of December 2017, rather than February 2021. I know that a diagram for that date already existed, but, if I didn't, I might assume it was created just for this document, in which case it would be bit odd.

The text goes on to mention Wendy butts, Stage butts, Hanham butts and Gazebo, but only the Wendy butts are shown on the diagram, and are not labelled with the term "Wendy". (Because the diagram pre-dates the other butts, but, again, the reader may not know this and is left to figure it out.)

If you aren't going to update the diagram, I would suggest briefly mentioning that the system now includes more butts groups than are shown on the diagram.

Test and illustration name clarified, references to water wheel removed.

I have not used Libreoffice's cross-referencing feature as I need to learn how to use it first.

Diagram not updated but notes added about changes since it was created.

2.1.2 Water Collection:
"Figure 2" is referenced, but in the annex it is listed as "Illustration 2".

In Figure 2, we do have more butts shown, but again they don't match the names in the text, because the system has evolved beyond the diagram. Railway Room Butts farm?

Reference fixed and note created about change of name to Hanham butts.

3.1.1 Visitor and Staff GUIs:
It's noted that Python is preferred because it has been used in the other elements of the system. Is it worth noting in addition, or instead, the reasons why Python was chosen for those other system elements? (Or referencing the fact that the reasons are documented elsewhere?)

This would be part of my assignment instead - I am required to provide justifications for choices backed by research. I feel that adding this to the requirements document is unlikely to be useful to stakeholders (eg you and WMT staff) and make the document harder to read.

3.2.2 Methodology:
As mentioned above, the description here contradicts the description on page 4.

In the second paragraph, I'm not sure that communicating via the web application server necessarily "improves" security, but rather provides what ought to be considered a minimum standard of security. I might therefore write "provides" rather than "improves".

Fixed and acknowledged with re-wording.

Page 13, just above 4.2 Software Requirements for the Staff Display:
The term "stretch targets" is used without definition. Is this a generally understood term that does not require definition, or does it need to be defined?

To me it denotes a "nice to have" requirement, which does not have to be fulfilled in order for the project to be regarded as a success, but should be fulfilled if time allows, after all the non-stretch targets are met.

Term clarified.

5.1 Operational:
It might be nice to apply some formatting to distinguish which rows in the requirements tables do not apply to the Open University Project. I'd probably do this to all the tables, for consistency.

I have used italics and added notes where relevant to denote requirements that are not part of the Open University project.

5.1.3:
The term "the Site-local Pi" does not seem to have been defined anywhere, and I'm not sure what is meant by it. What is the Site-local Pi?

Term added to Definitions.

5.1.4, 5.1.5:
Just to confirm: these requirements are being excluded from the Open University Project? I have no objection to them being excluded, but I don't remeber it being discussed, so just checking to make sure it's not a mistake.

May not have been discussed with you - my mistake. In a discussion with my supervisor it was noted that these requirements are probably beyond scope, as it might be very hard to measure, and because the system will be extended after the completion of the OU project anyway - the results would probably be made irrelevant by the changes.

Annex A, Illustration 1:
This diagram could do with a legend or key to the symbols used.

To the uninitiated, it would be hard to identify the sump, because it is not labelled "sump". I already knew roughly where to look for it, and I still had to think about it for a bit!

As mentioned above, Illustration 1 has been referenced as Figure 1 in 2.1.1.

Annex A, Illustration 2:
As mentioned above, Illustration 1 has been referenced as Figure 2 in 2.1.2.

References fixed as noted before, but diagrams not updated because I do not know how they were made, where to find them, or how to modify them, or if we have newer ones available, but I do acknowledge that extra clarity could be useful.

Additional changes:

Previously discussed clarification made to Section 3.1.3 "Copyright" as I have to temporarily hold Copyright in order to comply with degree requirements.

Extra comments added to section 2.1.1 to note that water wheel is no longer installed.

[hamishmb]

I will now send this revision to my supervisor as time is ticking on. I should note that anyone may change this document as long as it is documented here who changed it and what was changed - that way I can avoid accidental plagiarism.