Requirements Elicitation starting 8/12/2020
Re: Requirements Elicitation starting 8/12/2020
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.
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.
- Attachments
-
- WMT_River_System_GUI_Reqs_Iss_1.3.odt
- (458.91 KiB) Downloaded 64 times
Hamish
Re: Requirements Elicitation starting 8/12/2020
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).
Terry
Re: Requirements Elicitation starting 8/12/2020
Yeah, absolutely, I'm very appreciative of the feedback
Hamish
Re: Requirements Elicitation starting 8/12/2020
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
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
Re: Requirements Elicitation starting 8/12/2020
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?
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?
Hamish
Re: Requirements Elicitation starting 8/12/2020
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.
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.
Re: Requirements Elicitation starting 8/12/2020
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.
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.
Hamish
Re: Requirements Elicitation starting 8/12/2020
Says he, before providing several screen-fulls of commentary.
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:PatrickW wrote: ↑25/02/2021, 19:53My 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.
- 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.
As the 'other' ex-engineer, do you have any thoughts on this?
Patrick,
I'll leave Hamish to respomd to your 'nitpicks'.[/quote]
Terry
Re: Requirements Elicitation starting 8/12/2020
Okay, here are my changes and justifications.
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.
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.
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.PatrickW wrote: ↑25/02/2021, 19:53 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.
Amended in accordance with clarifications made over email - inclusion of noncommercial clause was the intention.
Clarified previous sentence to avoid confusion.PatrickW wrote: ↑25/02/2021, 19:53 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..."
Acknowledged and removed.
Description updated to refer to database and NAS box.
Clarified and new heading created to draw attention.PatrickW wrote: ↑25/02/2021, 19:53 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.
Test and illustration name clarified, references to water wheel removed.PatrickW wrote: ↑25/02/2021, 19:53 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.
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.
Reference fixed and note created about change of name to Hanham butts.PatrickW wrote: ↑25/02/2021, 19:53 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?
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.PatrickW wrote: ↑25/02/2021, 19:53 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?)
Fixed and acknowledged with re-wording.PatrickW wrote: ↑25/02/2021, 19:53 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".
Term clarified.PatrickW wrote: ↑25/02/2021, 19:53 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.
I have used italics and added notes where relevant to denote requirements that are not part of the Open University project.
Term added to Definitions.
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.
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.PatrickW wrote: ↑25/02/2021, 19:53 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.
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.
Hamish
Re: Requirements Elicitation starting 8/12/2020
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.
Hamish