 Right. Thank you, Candice. Now also about the handout, Candice, if you want to make mention of that. Yes, I'm going to go ahead and post in the chat a link to the handout that Rex will be going over today. So you can click on that link and you can download the PDF. You can also find this PDF on the landing page for the website at LinuxFoundation.org slash webinars. Right. Thank you. Welcome everybody. I'm an independent consultant here based in Northern Virginia in the US that of Australian origin if you're interested in where my accent comes from. I've been working with it standards for nearly 39 years now and while I've learned a lot about what to do I've learned a lot about what not to do. And a couple of things I'll just mentioned in advance here. Almost all of my work has been involved with software standards. And in recent years I've done a bit on process standards. The big difference is is that software standards can be validated. You can run all kinds of tools and things over them which of course you can't do with process standards. I would try to be somewhat generic. A number of things will touch into the area assuming that you're in producing a spec for software related technology. And I believe there'll be a session or some questions about letting you identify which you're doing would be interested to know that. Within the IT spec I've worked primarily with the programming language specifications, but also very large environmental and things like the Microsoft Office file format when they went from Doc to Doc X and all the associated things. So I'm the editor was for that for 17 years of that and we finished up with a 6500 page specification. Since then I've worked on 10 page specifications which is rather interesting. So let's click off now and sit look at the table of contents. You're seeing here a crude slide in a word file that exactly mimics the handout you can download so pretty much everything I say will be touched on in the actual text so no need to make notes. If I talk something extra I would generally suggest this is new and you could make a note about that. My intent is to cover hopefully the first 10 topics here we have a limited amount of time possible Q&A. So let's get started then. So firstly, we're talking about producing a formal specification and the audience for such a thing is there are three different kinds of reader. Firstly, people who are going to implement the build an implementation or create a process. Clearly they need to know what it is that trying to build and what the constraints and rules are. It's possible that somebody will be building some sort of a test suite or a checklist that can be used against it. And in that sense, an implementation does what they think should be done. The test suite checks that they did it, but the test suite might find errors or problems in the implementation and the two sort of sides feed off each other. So let's talk a little bit more about the test suite later. And then finally the users of the tools or process that want to be able to learn about what is the goal of this process what's included and what's not included. And what are the implications of moving the process or tool from one environment to another. For example, in a programming language environment you might say well, I've got all of this Java code. I'm going to move it from this environment from Linux over to Windows or such. And you have to go look at the spec to see what they say about what's guaranteed versus what might depend on a platform and we'll talk more about terminology later. So that's basically our audience, we're writing it for those three possibilities the first and the third bullet, possibly the second, certainly even if there's no formal test suite, people will be writing their own test in general. So the lesson to learn here that is, write a clear and concise charter for the formalization effort, one of the goals, and just as importantly the non goals, and separate the wouldn't it be nice to thoughts. I cannot emphasize that enough. And I've written widely over the years on my blog about romantic aspects of things that is the reality versus the romantic wouldn't be nice if the dreamy stuff. If you're doing a non trivial specification in terms of size or complexity involving companies or competition in the marketplace, you'll fairly quickly figure out you need to pin some things down about the scope of the project, and how far you're willing to go, and what sort of budget that may be involved. In that case, I'm a paid project editor for large projects, and, and these kinds of things so when you're when you're paying editorial staff to manage and maintain things. You're pretty quickly talking in the tens of thousands of dollars for the various kind of support model of these kinds of things so write down what it is you're trying to do, get some consensus, and, and separate and prioritize the necessary versus wouldn't be nice. So do we have any questions ladies and anything to do with number one. No questions at this point Rex. Right good. So now let's get into what's the starting point. Many many or most projects start with a person or a small group doing a project or research or proprietary project that eventually even start shipping. And once things become popular word gets out, then there's some interest outside of the original involvement, either in the same organization for other projects or outside organizations. And so, that's what I term about consolidating prior art. If you get some interest at that point so let's try to make this more formal and handle a bunch of questions and dark corners. And so, the consolidation of prior art basically says, let's take all the information that exists and try to pull together a common specification that involves and tries to consider pretty much all of those particular groups. The important thing is, is that can easily involve breaking existing implementations. So there are, there may be business forces involved. For example, when I started in 1984 on the sea language standard, there was something like 50 to 100 vendors mainstream vendors of sea compiles out there. Which had done things in slightly different ways based on their being incomplete specifications or it was not specified. And so being involved in compromise, and it could be business serious business to, you know, how dare you break my implementation of which I have 1000 customers and tell me it's broken. How can you accommodate me and things like that. So, basically, that's, I think the most common scenario, but again it comes with its costs. The design by committee is that you've got a good idea but it hasn't actually been implemented yet. Basically, you've got a proof of a concept, but you decided to do that. That's less likely used in the software industry. I'm aware of one project and that was the Ada programming language which was designed by committee to start with. And as you can imagine, that's a whole different process involving lots of different dynamics. And the good news for that is, you're starting with a blank slate. And you can do anything. The bad news is you have to do everything because you don't really have any sort of guidelines. You have to work in both of those in some sense the first one mostly because I'm consolidating on prior art by a widespread group of vendors and things. I've also had it from just from a single vendor. In the case of the C sharp programming language. There was an internal spec that it was basically entirely for Microsoft's internal consumption. And my job was to now make that applicable to the world at large and I 23 years later I continue in that role. PHP, which the language in which Facebook was originally written in has never had a full specification. And when I was invited to write one. Again, I had to deal with several disparate kind of audiences out there and implement patients and a lot of things that had never been specified. And that's the starting point to know exactly where you're coming from. And that will set the tone on the kind of organization you'll need to manage it, the kind of politics you'll have in terms of the compromise and such things. So very important questions anything yet. So now, number three, this may very well be the biggest business decision you will make because this is a business decision and so don't fool yourself other than that it'll grow and creep gradually. It'll take up time and resources. Firstly, I'll just use the term standard development organization as a general term of something that publishes a formal specification. Yes, it could be ISO it could be antsy in the US it could be the British standards and it could be Oasis consortium or whatever, or it could be your technical committee that you have created or about to create it. It's not necessarily a formally nationally internationally recognized idea, but that's the basic thing. Now it's interesting to note the procurement process of some organization such as the EU and the federal state government requires certain products conformed by accredited. So first of all, that suggests that you need to be publishing with an accredited whatever that means as the old, and they will have their own requirements as to what is involved in that. There will need to be some sort of a certification process as to say yes you do in fact comply and they might involve some tooling for that. So that's an extra thing. But again, it may very well be you don't have any of that, and it's simply an open source project that you're willing to share. And that's how things go. So in my case, the C sharp spec is now an open source project the world can contribute. Ultimately, we distill it into a PDF that is published through Edward international as a standard development organization. So we basically have the best of both worlds, the process of producing it is very informal, but the actual process of publishing it is actually fall and that's an important thing to keep in mind that maybe you could take advantage of as well. So a technical committee then is the one that produces the formal specification and as I said the technical committee may very well be the SDO itself. Again, stress most importantly, get clear in your mind the needs versus once make lists of them and review them from time to time to keep reminding yourself why this is a one to not a need. And then maybe you'll change priorities and certain ones might become needs as things evolve and as marketplace and arise. Now, the one thing I said that keep in mind if you want to go with a an SDO, then you need to decide that early on, because some of them have large and complex sets of publishing requirements. And the last thing you want to come to is to have a perfectly fine spec the industry knows and loves. And when you try to submit it to a recognized SDO, they require you to basically reformat the entire thing. If you're a 102050 page spec, that's not a big deal. But the 6500 page spec that I was at a draw for many years, when you were told that my approximations on what it would take to make it comply to the format was $100,000 plus of keeping time and the end result would be technically no better. And we would probably introduce errors along the way. So certainly, you want to know very early in the process before you commit to actually formatting your core spec into any particular manner as to where this thing is destined. And you might say, well, we're going to do it this way. And we hope to be able to delay the choice later on, you can only delay it so far. For example, if you choose word, or you choose GitHub, or some other tool, how are you going to get things done in one environment for the other? Most importantly, people join a technical committee for the technical challenge of what's gone, not for the formatting and the administration. And they've proofed it and made all kinds of fixes. And the last thing they're going to do is when you say, oh, we reformatted this now with tools, could you prove this to make sure we got it right? That is not something they're going to want to do. There are all kinds of interesting editorial errors that could be introduced in the transposition process can go into the published version. So, will you be bound by a particular set of rules? It's either yes or no. Once you make the decision, you should expect to be locked into it forever. If you don't, you're not locked into it, it's okay to know what some of the groups require out there and borrow various aspects, as some can make sense. Indeed, all of the standards that I've used that are outside of say a formal SDO have borrowed heavily on what I think are good ideas from some of those organizations. They're just not requirements. And so in the handout, you will have a URL although it's interesting here because yes, so if you've got the electronic handout, these are all hyperlinks, and you can go to the ISO directives, which talk about how to prepare something, along with the style guy which is above and beyond the actual requirements. And off the top of my head, those two combined is something like 100 plus pages. It's not a light commitment to say go the ISO route. And you would have to understand what you're getting into again before you commit to very much formatting. So you don't go down the wrong path. Now, this particular seminar of generic and that we're not going to talk about iso specifics in general, but there is a possibility we might offer such a follow on one specifically for ISO. In the poll and you should indicate interest if you wish to know more about that. Rex, we have a really great question from Christopher punches, which is, how do you differentiate between the want and need in the in the process and I think there's two components to that want and need in terms of the scope and want and need in terms of whether to take a project to SDF. Firstly, they can change. I find that every three to six months, I'm a different person in terms of my wants and needs for my business and other life experiences so I can maintain the list and I review it on a regular basis to see a circumstances change in reality, or my thinking Secondly, if you're in a small group or you're starting out as a single person or several people, get a core group of people to talk about these kinds of issues. And certainly you want people who don't necessarily agree with you you don't want yes people to say yeah that's a great idea. You need them to stand up and say push back no that isn't a good idea. And the more you know the list of needs you see grows, you need to then factor in what is the needs of the complexity of the technical committee you'll need and the resources. My boss says I can do this 5% of my time and now it's going to take 10 or 15% so be very specific about the needs and try to quantify them in terms of the impact they'll have on the specification the details so for example, you say it'll be really nice to have a test suite that we can run that all members can run against their implementations from time to time. I can tell you that is not a simple task to do that could be a full time job for somebody on a non trivial spec, at least for some months. So that's the best advice I can be is that review your own thinking and the situation and also have a small core group of people committed to it, who can discuss this kind of thing, and push back on a regular basis, if necessary. Okay. That's it for now. Okay, so conformance. That's a kind of formal spec and you can say, well, that's a wonderful thing that's precisely what I wanted to do. But how can somebody actually, how can you tell if some implementation actually complies with it. To the point, certain purchases of things will require there be a certification or that you pass the test. And the set of tests, particularly for software could be so large that you in fact, make this a commercial product. So when we did the sea language standard there fairly quickly were a number of fairly large and complex commercially available sweets there were three that I know of that were then available to run against it. And so the JavaScript committee, which I chaired for a couple of years a few years ago, as part of the committee activity does in fact have a test suite, but again you needed a very dedicated person or several other people to produce that otherwise you've got a spec and this is how the world should be, and then you have the world as it is, and who's checking between the two. If nobody is really taking that seriously, then what's the point of having the formal spec apart from ego. And so think about that, and the terms of compliance. And we talk about the degree to which an implementation agrees so the idea is that if you put out a new version of a specification, say version three, if someone is still on version two, some of them might be on version one, and they aren't going to immediately comply with three and they might not for a year or two. So anybody requiring compliance says well we can't expect that they have version three yet for a certain amount of time. There are people with partial implementations. There are 2.5. There are people that have extensions beyond and above that. So we'll talk a bit more about flavors later on. So the content of the spec will be text that is normative or informative or non-normative. The normative text says here's what you've got to do. You have to provide this capability and it has to have this syntax to invoke it and it has to have this kind of behavior. But you might also weaken that as we'll see later. Informative stuff is that oh by the way, we're going to be helpful and we're going to provide you some notes and examples. In a strict model, there are people out there who will provide specs that say well you know maybe you need a PhD in mathematics to understand this but that's not our problem. This is what we've done. The realistic situation is you've got a lot of people doing open source projects and they want to be able to read things in lame and sort of English with the few rules explained. And so it's useful to have examples of course of schema or of source code or output or data, things like this, which conforms or doesn't and explains why there could be notes as well. We said way back here 50 pages ago this was the case and that matters right here. We're not, we're not going to restate that because we don't want to say things more than once. But we're bringing your attention to the fact that you should go back and understand that term in this context. So informative text is done. And then you can have conditionally normative, you could say oh. If you support IEEE floating point arithmetic which is very commonly a decision in computing and programming languages, then you have to do this, but if you don't ignore this whole chapter or annex. So you can have, and you could have a paragraph or sections that are conditionally normative. And so the idea is, you have normative and informative and an implementation that complies completely has to follow all the normative rules. Now, how do you identify normative text. There are two common ways I've come in touch with the first here which is required by ISO simply uses the word shall shall not they may not and some others, which is sort of old English shall, they'll shall, they'll shall, etc, and not. That's the way it is that's required by them. And if you go that route so it's not just a matter of do I want an SDO, you have to understand the implication of choosing a particular SDO as to how that's going to impact your whole project. That may very well cause you decide not to go with a particular SDO at all, because of the onerous requirements. And so saying shall, for example in an ISO standard if I say shall, that's a conformance requirement but if I say must, that's typically the note or example, it's not normative it's not a requirement, even though it sounds like it carries the same way. Now another common alternative used in open source and others uses uppercase equivalence as defined in an RSC. So that's very common. They do stick out you can you can see them much more easily than a hidden English word like shall. And also, you can search for the mechanically in the source. So you could extract all the rules mechanically by looking for certain keywords without knowing the context of them so there are advantages and disadvantages of these approaches. So in an important way, how do you identify which is it being normative. Now, the thing too is that we'll talk later but if you're using a collaborative development environment to maintain the text say like a Google Docs or a GitHub. Every man and his dog can actually submit and make corrections and improvements etc. You no longer have a central pipeline of an editor managing a single document like in the good old days. So the editorial task becomes what I have to go review all of the changes that people have made to verify that they have in fact used the correct compliance terminology. So that is a change in traditional editorial model so again, you'll have to decide what mechanism you use to identify that no reason to invent your own scheme but you can take one of the existing ones if you're required to, or you can take the existing one that or extend it if you have other kinds of situations to deal with. Right now ideally, all requirements of the spec are absolute with regards to reproducible behavior, you do this and this is what comes out the other end, and you must not do this that's in fact not allowed. And so it seems a no brainer that it should be absolute in the ideal case. However, it's a widespread practice to have a number of flavors of behavior. For example, if I'm consolidating prior art and I have five different implementations already out there selling and existing find and providing a great service. And let's say between the five of them, they're using two different ways of approaching something. And then how do we deal with that you can you force three of them to change to the other two or vice versa that obviously gets a lot of people upset and breaking their stuff. Could you come up with a new approach and force all of them to be broken. That sounds like a worse idea. You could also say, we're going to make the implementation defined at the behavior implementation defined, which says the spec places no requirements on what you in fact have to do. You have to not break the world it has to succeed, but the vendor has to document in their own documentation as to what the behavior is. Clearly, if you are a user wanting to move from one environment to the other, then you need to look for those kinds of flags, because that's the stuff that can change when you go from say a macintosh to a windows to a Linux type windowing environment, for example, you have local specific things. So if I key in a name, somebody's family name and I have that converted to up or a lower case or title case. I, you know, am I handling a non USA English letters. And so certainly the behavior of certain things is local specific and we'll talk briefly about local a little bit later. This could be undefined or unspecified. This gets right outside of reproducible. I hate it. If you do this, all bets are off, we have nothing to say about that. So, again, you have to understand which ones you know you want to have and be prepared to add others. You come in saying it's always going to be absolute. That's an interesting rule, and you need to then revisit that from time to time. So, time goes on, and you find that there's a better way of doing something than you had. And so you would like to provide a replacement. Now it's bad style and respect to in a new addition to say, okay, we've rewritten the Old Testament here and this is what you've got to do because that's going to break everybody. If you give them one of revisions worth of notice that would be good industry standard could be a year or 612 18 months. We're going, we're giving you now a new way of doing this, and we feel so strongly about it that we're going to deprecate the previous way of doing it, and we may very well remove that from a future version of the spec. Now, most often that doesn't happen. It stays there as a recommended against historical artifact, but you'll still find software implementation that they're using it forever. And indeed, they have been rare cases where a committee dropped something and was sued into a very onerous long term drawn out thing to say you've broken something that's working in the insurance industry around the world for years, and you have no right to do that. So just think about deprecation. You have the ability better to get it right first time but right is subjective as time goes by when new techniques are available or you find the old decision was inadvisable for some particular reason. And then this is something not in the handout but I've already talked a little bit about, will you develop a performance test suite if your software based because that's and make it available to the world at large and implementers. So that, you know, that's a thing but again, that is a non trivial commitment. So questions about conformance or anything up to this point. Is there somebody still out there. No questions. Right now, a few legal considerations are not going to dwell on this, other than to say, for example, if you're in a committee and you're all making contributions, who owns those and things like this so some fundamental things there. Importantly, have at least one person in your group in the TC who's interested in this stuff and to learn about what the potential issues are. I mean, if you're using a formal and existing SDO, they will already have requirements about a non discriminatory and royalty free such things and whatever and copyrights and trademarks and whatever. So, again, most TC participants are there for the technical sort of challenges, not for the administrative or legal so make sure you that you don't want to get that way late. So we had an early stage of a stand I was in a person felt slighted that we hadn't handled his comments on early ballots, and he took it to his US congressman who tried to then raise it through ANSI within the US so again all kinds of interesting issues in my 39 years. So nothing that I want to raise there and I don't know that field so I can't possibly answer any questions about it but I think there are people in the LF and Seth and others can be brought to bear and possibly follow up webinars about some of these issues. On the legal considerations. Rex I think it's also worth calling out how important that scope that you mentioned at the top of the workshop here is to understanding the legal considerations here. When you define that project scope that really does become a bounding box for how that final output might be used and what licenses to the underlying intellectual property are going to be applied. I think things are very well connected. I also did get a question here in the q amp a does a mathematically formal way to write a spec exist or do you know of any efforts that are presently underway for writing. That's thought until we get down and talk about grammars and validation that might open up answer some of that and then we can revisit if there's still other questions but yes there are, there are, there are standards on on form specification syntax. And, bnf back as nerve format and extended bnf e bnf, but if we can put that one on hold. Okay, specification packaging okay so you're ready now to start writing something. How do you organize it. Well the simplest thing is well I want to describe a widget, and I can do that in 2030 pages and I can do it in a single part that is, it's a single document and we'll call it a single part it will be published with some designating number as a standalone thing. And maybe that's how you start out. You might have a multi part where in fact you have a related number of parts, typically each one mapping into a document physically but we don't care really how mapping works. And so what might that be for so you could for example say we have a core specification for some technology. And that could be in part one, you then might say, well yes but then when we apply it to this particular kind of industry, then this applies or this industry and you might have industry specific parts that follow on. And so people can then choose to comply with various part through that set, they comply with the core part zero one, and they comply with one or more of the other parts. And a part need not all be normative, you could in fact have a whole part that was nothing more than a tutorial test cases statistics research white papers whatever you want. And that could be anywhere in any of the parts, but you could have passed totally dedicated. So you're maintaining the documentation and related things along with it, but they're all related, and they all make sense to be part of ISO IS 12345, rather than have, you know, five numbers over a 10 year period that is no obvious relation between them. And so, so that's not uncommon for non trivial size ones. The 6500 page spec I worked on for 17 years had in fact four parts, although it could easily have been broken into probably 10 or 12. Multiple separate specification which are unrelated or not close to related. So it could change between this you could start out with option one, and later on realize you want to add more, and you change to a multi part presuming again your SDO supports that has some way to deal with that again that's useful to know up front, even if you don't think you need part two or three. Nice to know what your options are when you make commitments, and then three, again, you may or may not need that so again, consider how it might be mapped into the editing platform. Again, lots of things are interrelated here, and you really want to do the homework and read this whole thing and consider it in detail before you commit down a path, because then changing may be quite difficult. So, is your specification likely to grow with respect to the number of components, will you have optional components will each of those, you know, go into a part so that conformance, you can actually comply by providing 10 of the 100 optional parts. The components and not all of them. How revision of one component impact the others. If you've got everything in one basket, then anything you change from an editorial change to adding a feature will require balancing review and revision of that whole thing. Whereas if it's multi part, only one of the parts that the parts that are affected need in fact be changed. So think of the modularity there in terms of the administrative impact of maintaining this kind of thing. You could also on a multi part or multi specification, you could have different technical committees or subgroups within a larger committee, working on each of those. So again, very synchronous, they can meet separately different time zones, whatever. And so that's very important to do that. So you don't have the whole committee dealing with every little thing. You can also break the committee up. For example, as during those she and I served on the ECMATC 39 JavaScript, they used to be all in one. And now they've broken into a parent committee that handles business and core stuff, and they now have tasks groups one two and three below them, which are somewhat autonomous and deal with specific components of the technology outside of the core stuff. So again, think about that short and long term and you can see that some of these things take way out of the realm of a backyard project that you're thinking this sounds like a good idea. Okay, any more questions. We have a question on conformance using test cases. So this is, can you elaborate on how conformance using test cases could look like I'm writing a spec for a GUI program used by a small company. I, in the C sharp where I'm the only thing I've really spent time with, we've developed their own tool. So we're using GitHub, and inside of the actual spec itself, we have HTML comments, which of course you can put anything in there. But the syntax we put in there actually complies with Jason J S O N notation just because we chose to be. And so we have a tool that says, Oh, when you run into one of these, you can go in and extract the actual all the contents of the code block that you can go off and then actually excuse me, I'm getting, yeah, I'm getting ahead of myself. We do that for grammar, so that when you get to grammar. It actually validates the grammar, but we also do it for the, for all the examples of source code in there, we extract it and then have third party tools outside do that. We'll talk a bit more about that a bit further if I can just throw that one under that one. Alright. Any other questions. So we're going to write some words, but what format will it be in. If you go with an SDO that has more than a few rules, they're going to dictate that. But here's my 10 cents worth of 39 years of writing under those rules. And it's in bold. The shape and format of a specification should be determined as much as possible by the committee producing it. After all, one presumes they know their subject matter best and its audience, and they have more of a little idea of what the industry needs to tolerate being told that you have to, in fact, format your section headers precisely this way by say ISO doesn't impact the utility and correctness of the spec. And I, I for one push back at every one of those things that I say a busy word in the idea if the SDO has a whole division dedicated to maintaining what documents should look like. That's that's that's a solution looking for a problem. And it's just way too odorous. And so you need to think entirely about that as to are you being forced into an approach that doesn't fit what you think is the best model for your thing and again that can have impact on the way you go. So, I'm a now a convert to collaborating platforms. And while it changes the editing model where the editor used to be that the bottleneck and could do everything and control what went into the spec. That is no longer the case but the editor now has to go review it. But the idea that a member of the committee, or a member of the public in an open project could go online at two o'clock in the morning Tasmanian Australian time and say, Oh I found a typo doesn't look right. They've missed something here and actually make a proposed fix right there in real time is a fantastic thing. As long as you monitor that activity and they it's a tentative thing until it's reviewed appropriate. That will cut down on the editors administration and the frustration of participants no end, because they see a problem, and they can do something about it. Rather than reporting it as an issue and trying to explain it letting somebody else take up and apply it basically put your money where your mouth is, and tell us the solution and hopefully actually apply and we'll get back to you whether we think that's acceptable. So I can't understate that importance and allow the organization informed to be as lightweight as possible. Certainly if you go GitHub, that's lightweight by design. It's frustratingly lightweight because he's all done I want to underline something and there's no way to do that, or I want more out of tables that I can actually get. And we can talk a bit more about that later, but the intent to be as lightweight as possible I think is good. Maybe you can have other tools to render that can add certain things. And so again, allow the organization maximum flexibility deciding style spots. I so tells you that anything in a constant with font has to be courier new. And it's very hard to find modern publishing people in the world who think courier new is a is a pleasant font to look at versus something else. And so, and whether you have what bullets what symbols use for numbering, all of these things could be dictated to you that you don't care. You know, tables within tables in in ISO, all kinds of stuff that can severely impact your spec and where you might want to take it. So, here's my editor wearing my editors hat. The SDO shouldn't get in the way of the experts right in the spec. All right, so I feel extremely strongly about that. Yeah, we have a, yeah, we have a question from our friend Joel. Joel points out and this is related to versioning of a spec that spec specified technology is generally always evolving new features breaking changes, etc. When you're starting to write a specification, is there a general rule when you can call that version. So complete. Does it have to specify everything in a technology or can you call a subset of the technology one dot oh if your content meets a particular goal that you set out to meet. Right. Yeah, so certainly part of the charter which we may modify over time. So, I in the JavaScript world, they went to some years between releases and the industry was saying well we really want, you know we know we're all working on stuff, but we need some something for procurement whatever so they bought into the idea we are going to produce a new addition of the spec annually in March, April, May, whatever it is, and you can bank on that and whatever we've got completed at that time we're going to put in there. So that's fine and they've done that and the C sharp spec we're also moving to an annual one although we're tracking commercial releases. So, when you go out there and use a version of C sharp is version seven or eight or nine or 10 and aspects of tracking that and so we're constrained to make the content of the spec match what was actually at that particular level. And so there's, you know, but you need room for middle ground to be able to say we're going to cut off. And but again, when I, when I work with Linux foundation on some of these things like STDX had its own worldwide numbering scheme. And we were going to do an ISO standard we wanted to call it version two, because that's what the world knew, even though it was the first ISO standard. We took some flat for that we said no you don't understand the world knows this as this particular version to and we need to, we need to follow the industry lead on tracking the numbers. Certainly, important to revise revisited times the scope and how you're doing things always take longer to deliver than you believe. So you may have good reason to say we're either delaying the release or we're going to ship it with fewer features than we had anticipated, as long as they all hang together, for example. Right. Right then ain't we talked a little about there. How I'm in favor of that so I'll skip by that. Now, in either of the approaches here. Let's say you go with ISO and ISO actually requires you to do stuff in word you say well that's over my dead body and a lot of people say that. But then you basically have the format you're working in if you can get a collaborative mechanism is the format you'll deliver. But it's entirely possible that you will be in some other environment where you will maintain the source of the spec in one format, and you might have to, or you might have to or you might choose to render it in another format. Like Word or PDF or HTML course can come out of Markdown with some table of contents and things like that. And so you want to then understand what tools will be might be involved in doing that. For example, as I said, if you want to have tables more than what GitHub can do, or more than something, then you have to put in raw HTML. Now any tool that converts your GitHub Markdown into something else now has to understand all of those kinds of exceptions and deal with it and pandoc and various other things will not know how to deal with it. So you need to look at what tools might I need to help me either to publish the spec or to verify and do certain kinds of checking in that spec. So let's move on, because that the next one will comes into part of that as well with the tooling. So now, if you're dealing with a programming language, then you clearly have to state the syntax of each particular kind of statement or form and these kind of things. And you can use a formal grammar notation, or you can describe it in narrative. So the earlier question was about is there a formal way to write things. And so, yes, you write a formal grammar, you could write a formal grammar for English or Latin or French, although it's impossible to get correct because the exceptions to the rules and the whole context. But when you write a formal grammar for your own sort of language, then you can make it as explicit and ambiguous as you choose. And that's certainly the technique to be involved. And that, as I said, there's an ISO standard, I believe for BNF back as new format BNF you go to Wikipedia and extended BNF. And, and there are others out there there are there are numerous others. And in the C sharp world, we have switched to now. And that's why it does have its own limitations in certain ways. And there are other tools in the, the Unix world you have the Lex and yak and various other ways of dealing with grammars and bison, and there are all kinds of formal grammar notations out there. So you don't need a very complex language, for example, and you're not just constricted to a programming language or other applications. If you write it in narrative, you'll have all the imprecision of writing in narrative. And that can be easily unambiguous in English and probably most other languages, using both, but not overlapping using a formal grammar, which is now normative, and that's what has to actually happen by implementation. You can then argument that in English narrative to provide the semantics. What does it mean when I have this particular construct and exceptions. And so the combination of the two. It's very bad style editorially to say in the narrative, what you've already stated formally in the grammar. It's unnecessary, and the two will get out of sync over time. Add new functionality to the grammar, forget to update the narrative, etc. And which one wins, and you'll get unnecessary queries of that. So, for example, you might be building a library. Oh, here's our library to deal with financial things in a Java environment query facilities. You have a configuration file, maybe you're building a tool or you have a process. And this is how you configure all of the particular people applications are going to use this. And what's the syntax of that configuration file, don't invent your own, at the very least use XML or something like that. But that will have a grammar. If it's in fact XML, then you'll write a corresponding schema for that. And that will become part of the normative specification and says that, okay, this particular feature has to have this construct to drive it. The grammar for it expressed as an external schema. And so a script, you could have examples. Here is a script you can feed to this tool with those all kinds of queries and here's the required outcome. So again, the script itself would be written according to the grammar, and it would be an example, but it's in fact needs to be valid for that particular thing. So if we talked about this, no value is added if the narrative simply repeats what the grammar indicates when we talked about that. Now, it's not always possible or desirable for a grammar to be complete. In which case, the narrative can be used to add constraints. So the grammar might not be say 100% of things. If you say, if you give me a query, you have to put these things in this order. And it may very well be that there are exceptions to that rule that are not easily expressed in the grammar, or clearly, or at all. And so you say yes in theory, you can construct a query so in English sentence, you could say, the man carried the house to the lake. It's not likely a man can carry a house, but that's not syntactic that gets to do with the meaning. And so you could very well say, well, the subject has to be a noun that's plausible or whatever. So you have a constraint that says, well, yes, the syntax allows this, but these particular kinds of occurrences or instances of this are not allowed that is the grammar is constrained as follows. So that's certainly normative, but it does show that the grammar, as complete as it is, might not be everything that there are exceptions to the rules and they might be expressed in in language narrative form, rather than some formal. No, if you can do it formally, all the better. So it can be very useful to be able to programmatically extract the grammar from the specification and run it through some tool. Firstly, you, as I said, in the C sharp spec, we have an HTML comment in the markdown, and it says okay, the following is a grammar, it detects the grammar, and it will then extract that right out to a file and run a particular grammar which actually extracts it for the whole spec that it all has to hang together. Then it runs a tool that actually validates to see if the grammar makes sense isn't ambiguous. There's all kinds of reasons the grammar might have syntax errors you've got it wrong it's ill form. And so, and then, as time goes by you add a new feature to your spec, you need to extend the existing grammar or add new rules to it. You need to make sure that correct and you need to make sure that when you copy that into the spec itself, you don't introduce editorial errors by misspelling or those kinds of things. And so, not necessary, but if you don't have this capability, then it's at the whim of the editor or reviewers to visually check to see that any grammars cited in the spec are actually valid. So this is an important thing to have, but non trivial to build and to manage. So what notation will you use. How will you express constraints. Will you have a tool that allows you to programmatically verify these kinds of things. The best time to find out about problem is minutes after it was created when the editor, and they made a change that wasn't valid, rather than months or six months later when you do something you're ready to ship the spec, and you find there's something broken that requires non trivial revision, and things like that when that long after people are done with that consideration. So again, collaborative stuff with tools is a good way to go. We've got one that's related to a different kind of grammar. And that is, is the Oxford comma allowed and specification writing. I think this is a great question to kind of speak to that editorial narrative points we're making Rex. Right. I have started using it probably in the last 10 years once I understood it. In, I think 99.99% of the cases. It doesn't matter, but there are occasionally things that do. And there is in fact an interesting case out there a legal case where a multimillion dollar settlement hinge on the presence or absence of that comma. That's the scariest situation, but for formal technical writing now I use the Oxford comma so the last entry in an enumerated list before the end of the year always has a comma. So I think practically it doesn't hurt. Again, whatever approach you use will be in your editor's guidelines. And when you're reviewing contributions by others, you have to go through and make sure that is the case. I think it doesn't hurt. And there are theoretical and maybe practical cases of it might help like you required to have a and B or C, you know, and things in the precedence ordering and how that works in terms of English. And so again, the Oxford comma and notes or some notation that you explained early on helps to understand potentially ambiguous situations. Any others. I think we've got about five minutes left. We're a little late but we're having good to make for the last thing we'll cover was 10, which is essentially the same thing as the grammar. So if you've got fragments or we said the grammar would include things like XML schema, for example, but if you've got examples of data and code, or configuration files or whatever, and you put them in the spec. It would be really nice to know that they are syntactically correct, and they actually produce the data you say, or that this is the data that results from some particular situation. Again, we put HTML comments in the GitHub stuff. And in the handout, I've given you URLs to go and lead the user manual for some of these tools to see what all we've at the syntax we've used and how we've done that. One fine day I thought maybe I should start an open source project to try to do this in general and see if we can make it usable across multiple projects so basically. It's important that examples are well formed work and produce the claim behavior. It can be challenging to build the tool to extract this, particularly when they contain only fragments. So when the example in there you extract is a standalone thing okay done, but if it's in fact just the relevant three lines of a 50 line program, how do you get the, the infrastructure, they're behind that, and we've done a pretty good job of the tool that does that in the C sharp spec to which I provide a URL but again, non trivial things to think about. Now the rest I think you can read offline it gets more into nuts and bolts, other than to say that if a mainstream aspect that fails to recognize and handle other than USA English characters and source files and data might run the opposition that's not a spec failure. It's not a project of the software failure but the spec itself would have to factor in what it says about any restrictions on what kind of environments intended to use so the scope could say this scope is for USA English, or it's for this or that or whatever. So, the rest then gets into nuts and bolts of details of things which have a little more information in the actual handout itself. So, questions. We have one last question, which is do you have any advice for distributed systems composite systems for example that are composed of vendor products minimum with minimal development to implement beyond integration glue. The question asked here says I'm unclear on how external references such as itf protocol RFCs or vendor product dependency should be represented in a spec. I'm not sure I fully understand the question, do they mean that the specification is distributed. I believe that the question speaks more to how, like a specification that might be created by multiple systems coming together this author maybe. Certainly, the accepted way of doing that is that it don't you're utilizing other specifications that are out there, and they are course under control of another group. So you refer to them, you have a normative reference that says by by insertion. It's as if everything in there is a normative part of the spec and is a requirement. You can have a bibliography that has informative things that all this provides extra information that is not necessary so certainly you can bring those into the phone and certain SDOs require that you get permission from those referred to places so they know you're referring to them. And the most important thing is, is that when you refer to other specifications, whether you choose to make them dated or undated references. If you say we're referring to a unit code or to some IEEE, IEEE or IEEE, then is it this particular year. If you say a year, then the world knows that your version of this spec is dependent up to that point and doesn't rely on anything that's evolved since then in the dependent upon specs. And then you'll have if they, if they modify their spec then you would need to monitor that and decide whether or not you need to modify yours to take account of new requirements and changes maybe they've deprecated some facilities. Alternatively, if you have a dated reference to it, excuse me, undated, then you're always pointing to the latest one. The good news is you're always pointing to the latest. The bad news is, you might not know there's an even later one that has requirements that don't agree with what you've actually done, but you need to monitor what they are doing and probably create an informal, if not formal liaison between your committee and their committee so that you're each obligated to notify the other when you make decisions that might adversely affect what they're doing or could impact what they're doing. That would just simply be a courtesy. One other thing that, when we talk about distributed, I've worked on a project in the last year or two, that's a web-based standard. That is, it doesn't look like a single document. That certainly is the way most of us deal with things these days. It doesn't fit the model of, say, ISO, or even equity and national, I'm not sure about our aces. So again, if you would like your spec to be published, basically as an HTML sort of table of content front-end to GitHub, then go for it. But again, that's not going to be acceptable by a lot of the mainstream international and national standard development organization. Yet it is the way a lot of us do stuff, and it also can minimize the way, you know, the world has long since stopped thinking of text as a paginated fixed-size, you know, A4 or US-sized page. And so again, that should be a factor in this decision-making. So again, last chance of questions? All right, then I'm done, ladies. Thank you so much, Rex, for your time today and thank you everyone for joining us. We just launched one last poll to see if you are interested in a follow-up Q&A on this topic, so please take a moment to answer that before you log out. Also, just a quick reminder that this recording will be up on the Linux Foundation's YouTube page later today. We hope you join us for future webinars and have a wonderful day. Thank you so much, Rex and Candace. Thank you, ladies. Thank you for attending, everybody.