Meeting minutes
Agenda Review
<kaz> agenda for today
Ege: Today, we will mostly work on the use cases coming frmo the TD
… but first we are going to take a look at the minutes from last week, Thursday
Minutes Review
<kaz> Oct-24
Ege: Wasn't there, but I talked to Michael Koster and Kaz, will scroll over them, let me know if you notice anything
… (scrolls through the minutes)
… okay, I don't see anything, so I assume that there are no remarks regarding the minutes and that they are approved
Minutes are approved
TD
Basic consensus
Ege: I think we agree that all changes no matter the size should have an explanation
… be it issues, meeting minutes, or documentation
… do other people have different opinions?
Ege: I am just saying that changes should have a description
McCool: I think we are still bundling together use cases and user stories
… I think we should seperate the two more clearly
… fine to submit new use cases
… no need to do a one-to-one mapping, just to be clear
… have prepared a template that we can take a look at
Ege: But you agree that any changes need a textual description?
McCool: Agree, need to be grounded in some kind of user story, explaining the connection and who wants it, i.e. the stakeholder
<EgeKorka_> proposal: all changes to the TD specification MUST be grounded by a textual description on why the change was needed
McCool: user story should be summarized in one sentence, but the template allows for more detail if necessary
… to explain technical details, but that should probably rather go into a technical description of a work item
Ege: Just posted a proposal in the IRC
McCool: I agree with the proprosal
Kaz: Personally agree with you two, Michael and Ege
… I think there is not much differences between your approaches
… I think Ege is looking at the matter more from a bottom-up view, while Michael has a top-down view
… therefore, we need to clarify use cases and user stories
McCool: I think Ege is more about documentation
… giving a reason
… instead of top-down or bottom-up
… can do the documentation in various ways, need to agree on how to do it
… I agree that the proposal is just a high-level view
Ege: Are there any objections to the proposal above then?
<EgeKorka_> proposal: all changes to the TD specification MUST be grounded by a textual description on why the change was needed
RESOLUTION: all changes to the TD specification MUST be grounded by a textual description on why the change was needed
Ege: If there are no objections, then I would turn it into a resolution
The resolution is accepted
Necessary Description for Work Items
Ege: I think the reusable connections work item is a good example for how we want to approach work items in general
… (shows the current markdown document)
… all of the work items should have a similar documentation and rationale, detailing what is "annoying" the developers
… I discussed with Kaz and MJK that this is enough from the W3C Process point of view
<kaz> I think the reusa|Work Items document - "Reusable Connections" as an example work item
McCool: I think this is excellent work, also explaining some requirements
… I think we need to make the connection back to the end user scenario
Ege: True, currently this is more written from the developer's point of view
McCool: I think that is fine, we just need to put the end user's point of view on top of that
Ege: Is already covered to a certain degree and already possible with the current TD version. But currently have a reverse process that maps new issues to the work item
McCool: I think generally, an issue should identify a problem
… bundling issues together to a work item is fine
… my suggestion would be deferring the documentation of the existing features and focus on new features
Kaz: I think for that purpose the problem statement here should not only include the problem statement from the developer's viewpoint but also the end user's
… could be added as a subsection
McCool: I would rather put that into a different document in order not blow things up
Kaz: Maybe you misunderstood me
… don't think this is an actual template
… it is more like a general description of work items and since you mentioned that user stories need to mentioned, I thought we should maybe put it here
McCool: I would rather not do that and keep user stories separate, in a separate .md item and then link to them
Kaz: I am okay with that, I was not focusing on the acutal Markdown files
… I am not saying that we should put everything into one file, I am rather talking about what information needs to be put into a work item
McCool: There is a feature request, which is talking about what is needed and why, that could include a use case and a user story
Kaz: Maybe before diving into the details about work items, we might want to think about the format for user stories
McCool: We also need to think about the internal process
… also need to cover that, for now we can just use a template for PRs (?)
… I would propose that user stories and feature requests become individual files that can be submitted via PRs
… in general, I try to avoid adding new use cases, as we have enough already
… I am talking about the general process
… my suggestion is not making it more complicated than necessary
… explain it in the README somewhere, provide a template for PRs
Kaz: I'm OK with either approach, (1) Ege's approach starting with the work items here or (2) McCool's approach once thinking about the process instead. Ege, how do you want to handle it?
<kaz> Work usability-and-design.md
Ege: The current Markdown file is already very verbose
… readers cannot trace back features to use cases really well at the moment
… is also not demanded by the W3C process
… Web of Things is more about developers, not that much about end users, the developers are the ones that care about the end users
McCool: We need to provide the context
Ege: That is a good way to approach it
… going back user stories, having a single sentence summary for the user story would be nice, also for putting it into the TD spec
McCool: My intention is to collect user stories and put them into the use cases and requirements document
… or rather the user stories and requirements document
… for linking back to them from the individual specifications
… want to extract and publish them eventually
… my reason to put them into separate files is to be able to link to them
… but also to put them into a document and have them as a publicly visible motivation
… is fine to put them with the rest, but eventually we should break them out
Ege: I always think about the developer
… let's take "observable" as an example
… would like to provide a way to link back to the "backstory"
McCool: At the end, we have assertions, to which we can link from user stories
… would be fine to link to the assertions from the work items, not necessary to link the other way around
Ege: Agree with that
McCool: For that we need stable links
… linking into the other direction might complicate things
… with the assertion ID, you can search the work items for it
… not as easier as a hyperlink, but it will still be connected
Kaz: The mapping between user story and feature is useful, totally agree
… but from the W3C Process point of view, we also need a link from the requirements to the work items
McCool: If you have user stories separately and work items separately, then we can link from both to each other
… to me a user story that says that it needs reusable connections is good enough
Kaz: as another high-level discussion, I think everybody here is OK with clarifying the mapping among (1) User Stories, (2) Requirements, (3) Work Items and (4) Features within specs
McCool: The user stories connect the uses cases and the work items
… and then we can link between them
… do not need bidirectional linking, can just search
… but we need stable links
… trouble with putting everything into a MD file is that changing the title might break the link, prefer linking to files instead
Cristiano: Just wondering
… I am okay with not putting the back link
… but wondering why we cannot make it handy for them
… wondering why we cannot just put a back link there
McCool: My rationale is that it requires a lot of maintenance
… can always just put everything into a note and then link to that
… but it does not have that much benefit, while causing us a lot of work
Cristiano: Got it, in the CG we were asked about that, so I was just wondering
McCool: Something we can do is putting it into the implementation report eventually
Kaz: I can understand what Michael McCool means and I am generally also okay with that. However, potentially we could also think about using some additional tooling for that if cross-reference linking would be really useful.
… however, we should probably rather focus on the content and what should be linked first
McCool: I am fine if Ege would provide the necessary tooling
Ege: I am a bit lost at the moment what is needed from the W3C Process point of view
McCool: You are dealing an excellent job, Ege, we just need to provide one sentence that links everything together
… we just need to have an "elevator pitch" for each feature
Ege: Let's go to your proposal from last time in your presentation
… have you updated your presentation, yet?
McCool: I did, there is also a PR in the use cases repo
McCool: The template now contains Who, What, Why, and optional details
… so, for example, a "What" would be reusable connections
Ege: (Starts filing out the template for the work item)
Ege: So the "Why" could be to support connection-oriented protocol or cases without the usage of default terms
McCool: Could also be split into two user stories
… might be a better way to strucutre it and make things easier
… I would also say "to support connection-oriented protocols like MQTT and WebSockets"
Ege: Or rather "to better describe"
McCool: Sure
… the "What" part for the second user story would be the same
… maybe we also need to identify sub problems
… the "Who" for the first user story would be something like a "deployer of devices with connection-oriented protocols"
… can be expanded upon later
Ege: The second one could be the person that is making the TDs
McCool: So you see, the two user stories have different targets
… for problems, you could also have headers for the subcategories which you could link to
… so the second user story is also about avoiding redundancy
… I think from this work, we learned something
… that there are sub-problems and there are actually different user categories
Ege: I think the user stories will help us writing the problems
McCool: Will also help us linking giving a reason for our features
… could also be only single sentences
… use cases can then also be linked later, like greehouse or webthings
Ege: Kind of reveals, that the use cases are kind of irrelevant for standardization
McCool: But it is still in your head, you just need to write it down
… could also come from the other direction, I want to build a greenhouse, but I don't know that I could use Web of Things for that
… so this direction is also useful for this kind of people
Kaz: I am okay with the list and this looks good
… just wanted to give some more explanation of the W3C Process
… at the transition stage, we need to link all the features to requirements
… having use cases would be useful for ourselves to understand the rquirements, so this approach is good
… my only question is whether we really want to turn the descriptions into consolidated single sentences or not
McCool: We don't have to, but it forces you to be concise
Kaz: I personally think the current style having "Who", "What" and "Why" is nicer and clearer. In addition, we might want to have some more questions like "How" and "When", but maybe that could be added later (=not within this "user stories" template, but at the later stage).
McCool: We could add something like "When", for example, but usually it is only "Who", "What", and "Why"
… that is the usual style
… can also be more than one sentence, but it should not be more than one line in general
AOB
Ege: Any other business?
... not hearing anything, so we can adjourn the call
<kaz> [adjourned]