Whatever happened to the "Gold Standard"?
lardom
Posts: 1,659
I thought there would be a board of established programmers formed to evaluate new objects prior to submission and that this would replace the OBEX. A common standard is a good idea. Is there still any interest in the forum?
Comments
The documentation issue was up for debate, and the question was how to document Spin code effectively and with nicely generated documentation. The issue we ran into here was a) coordinating with Parallax education on how they are documenting their PropGCC code (we want the Spin documentation to match) and b) developing a tool to automatically process Spin files and generate documentation. This tool could be delayed, as long as the standard is there so that it could be developed later. In the end, we settled on the Javadoc style of commenting.
The submission process was also in question. Mostly for this we were waiting for a private subforum to be made so that we could test out the process. There were (are) a number of challenges with getting objects submitted. First off, there needs to be a section of "highly reliable" objects that are relatively set in stone, and very reliable. These objects would be things like FDS+, real random, an I2C driver, SD card drivers, and other "true and tested" types. Then there needs to be a section of "community" objects that anybody can submit. This would more closely match the current obex: objects that may be useful to somebody, and vary in quality.
The challenge with the submission process was: how to do it? The limitation is that we can't use anything that would cost money, either to buy or maintain. In the end, we came up with something like the following:
1) A potential object would be submitted by creating a thread in a new subforum ("The Gold Standard Submission Forum").
2) The object would be objectively evaluated against a checklist. Discussions would take place in the submission thread.
3) If the object passes the checklist, then it is added to a Google Code repository (the "new obex").
4) Objects in the new obex can be improved and modified via contributors and the Google Code collaboration software.
5) Objects in the new obex that are high quality enough are submitted for inclusion in the "Gold" obex. These objects are then tested by Parallax personnel, and included or rejected.
I can't speak for the others, but I know that I started working full time soon after the obex push, and that's been part of the reason on my decline in participation. In any case, at least it's Propeller based.
Maybe we can get that new (for now, hidden) subforum for the Obex when the Prop2 subforum is made?
-Whoever does the forum administration. Plus, a few forumistas who volunteer to moderate on that subforum, to make sure that only submission threads are in there. The forum has already been approved (or was).
One benefit of posting an object to the forum before submitting it to the OBEX is that we have a place where we can stay updated on OBEX activity. The more I think about it the subforum could be titled "OBEX"...just a thought.
People submit to the regular OBEX and when or if it gets reviewed and tested by designated people it gets moved over to the GOLD OBEX. If it passes muster.
Code can't be reviewed or tested by the submitter. Has to be a second set of eyes.
That will allow code to be submitted to the the regular OBEX without any evaluation and the good stuff can be transfered to the GOLD OBEX as resources are available for the review and test process.
Having said all that maybe a flag to be applied to code in the existing OBEX that designates it as good code. Note I use the term 'good code' as opposed to 'gold code'. I consider computer programming to be both a logical and creative exercise. People have different styles of writing whether it's computer code or novels.
Make sense?
Sandy
That is, how would a Gold Standard be different form the regular OBEX?
The difference would be that the Gold Standard code would be properly reviewed, tested and documented.
So the question was "What do we mean by properly reviewed, tested, and documented?"
The conversation got to the point where we discussed auto-documentation from the code itself.
But there is much more involved, for example, test: In order to test, we need to know what the code is intended to do. So this means requirements, and requirements are on many levels. Most folks don't realize the difference between High level requirements (the SD code reads SD cards) mid-level requirements (it conforms to standard XXX and supports these functions 1 through NNN) and low level requirements ( Function 1 is called <name>, has these inputs, these outputs, and does this processing). With this level of requirements, one could write tests that could truly test that the code does something specific, and does it correctly. Without this level of requirements, it is not really possible to test that something does anything specific, since nothing specific is defined. And although this structure of requirements and testing is quite common, it was not determined how we could arrange this for the parallax community to handle, or even if the community could even understand a benefit from such a process. If the community could not self - operate the process, then the cost would be far too high for Parallax to staff.
The auto-documentation would have given us about 10% of what we would need for a "Gold Standard", and in my opinion that would be that last 10%. The more important steps are the up-front planning steps of recording the requirements, and creating the tests for those requirements, and recording the results of the tests, and finally maintaining the tests and records. The code itself is only the final 10% of the effort. (I use 10% a lot here, the number varies in real life circumstance, but its close enough for this discussion).
Without all the this, and repository would be not different than the OBEX, and that's already fine as it is for what it does.
Would anybody be interested in a full process? (What I described is a just a very general, rough outline, but it would be a starting point for discussion).
I am discovering for the first time just how much thought you've given this. It would frustrate me to no end if all my work was forgotten after a standard thread went idle.
I have doubts that OBEX would every be replaced by this as the OBEX represents a lot of person's best efforts to share what they know and have learned. While that might not all be rock solid software code, there is some value in all of it.
http://www.parallaxsemiconductor.com/support/goldstandard
It has been my experience that; Feedback, Discussions, and Program Fixes, user Examples and such, get lost in a landslide of generic Parallax Forum topics, where collecting and sorting relevant information by a new OBEX user (me) is difficult at best.
I like the idea of the "Gold Standard", but from my prospective, the overhead and sluggishness may prevent its existence (I am still waiting).
So what about direct "Crowed Sourcing" for Object/Software Review and Revisions?
Again from my prospective, The current problem with the OBEX is matter of "Proximity". That is; relevant information, user reviews, suggested fixes, Revisions, and actual user examples are not stored, or linked, near the Objects source. I suggest a System for Revision Control with Branches where new ideas can be suggested and reviewed by users. And, maybe a single indexed Forum per entry, where strict peer pressure (to reduce Spam and Off Topic Discussion) prevail.
I suggest something like "Git" (as in the "GitHub") and with a dedicated Parallax Forum support. The original Object Author can easily retain as much (or as little) control of their object/software as they desired.
Regardless, of the method use, I think "Proximity" and "Links" are keys to any libraries success.
Regards,
Eldon
We assembled a customer team to address the problem but even the team needed more response and support from Parallax than we were reasonably able to provide. The customer team did a lot of discussion and my personal feeling was that the process had too many requirements (nobody's fault here, but there were many long messages), perhaps to the point that nothing was going to get accomplished in the end. We also didn't appoint a clear leader. There's no doubt that the GSL process needs input from Parallax to get accomplished and we were weak when it came to providing useful direction. Both Daniel and I recognize this now.
To be frank, we've got an awful lot going on in Parallax. Our technical team is quite small and not growing immediately until we have P2 in production. Our internal efforts are focused on Propeller 2's release plans, and in the meantime all resources are focused on supporting it's development.
Properly developing and implementing the GSL would require more community support.
I am at the point where I can provide limited direction on how we go about this effort. I'm sure Parallax could outline our goals, at a minimum. From there, it seems that we need to find an existing on-line system for managing the code and people who can adopt the process of qualifying objects. We'd use this code base in our tool distributions. Parallax would need management authority over the system, but we'd want others to develop it [yeah, that might be asking an awful lot from volunteers, but a key need of ours as GSL must be able to mesh with our other efforts internally, without barriers]. Requirements for submitting code - and having it approved - need to be reasonable. They shouldn't set a bar nobody can reach, or one that discourages contributors by asking them to be reviewed in a committee atmosphere.
If we can set another fire to this topic I'll be there to support it on behalf of Parallax. Third effort is our last chance. I'll check back in this thread over the next day.
Thanks,
Ken Gracey
I did a $h1t load of work on this, process is what I do. But I did it as a side discussion, as it was tangential to the main work the group was doing. And most likely an option that would not be executed, as the cost is perceived to be high. If rreality, the cost of NOT doing a proper process is always orders of magnitude higher than doing a proper process. When its one guy, we don't care since the guy does whatever. When there are 2 to N people working together, process is quickly shown to be indispensable.
But, DESIGNING such a process is the interesting part. That is, if I inflict a process on somebody, they will resent it and it will not be used and fail.
However, if we (notice that this must include the participants) CAPTURE a process that everybody (or at least some group) already uses, we can clearly lay out each step, and teach it to others. Then its a simple task to "edumacate" newcomers.
The unofficial P2 documentation project is one example of a development process being formed that is potentially appropriate to this community. The DE0-Nano is another. In these threads, folks ask questions and they get addressed. Folk play nice, and things get done. The community members participate (review and contribute) because they want to, and the level of work is exactly appropriate to each person ability and availability. And the work is steered by the members' wants and needs, with no particular leader or other formal direction.
I would want to see a way to track each item, to ensure they all get addressed and nothing falls through the cracks, but its still too early for that. The process must be allowed to gel and stabilize before start to touch it, or it will fall like a souffle. So aside from this post, I will keep out of all process discussions, until specifically invited.
Actually, we let things just happen, those threads should provide us with a template of our actual process. The only thing thatt is lacking is data collection, which can be done after the fact, from the threads themselves.
Guy writes code, guy posts code to forums, perhaps guy posts code to OBEX. It works for him. Job done. He moves on to the next thing in his life.
Same goes on with github and other repositories. What do they have now, 4 million repositories? Bet most of it is marginal, out of date, unmaintained, does not work with the latest rev of language or OS etc etc etc. No matter, it's there as a backup for the guy who wrote it if nothing else. Documentation? Now really.
Looking at it that way there is no need for OBEX. All that stuff could be in github or whatever, even a Parallax run repo system. If anyone needs some code and it needs fixing first they can fork the project and maintain their own version. If people use it it will get improved.
Seems to me that imposing standards and "process" on a huge catalog of existing code is lot of work to ask for. Except for a handful of important objects.
?
Jonathan
There we have both extremes in posts 10 and 13.
The expert level programmers can look at code, and determine if it is ok and/or bend it to their will; the new comers cannot any such determination and a cannot rely on any give bit of code to do anything in particular. Newcomers/beginners do not know the behaviors to analyze and modify code, these processes are learned over the long term in to course of becoming expert.
Those were the issues we tried to tackle. It turns out to lead to larger and larger questions. The bulk of the work would have to be performed by experts who don't need it, and any result would be for the benefit of folks that are not equipped to use it.
There is no quick, easy, cheap solution for this. So the best course of action seems to be let it rest until we have more information and new insights.
Now THATS a good idea. By the nominations, the process is driven by the community, which give evidence that somebody tried it and found it to be useful. The author (and users) know there's interest, and get motivated to possibly put in more effort. This could allow Parallax to also invest effort in the items that might yield the most benefit.
The Gold Stand indends to be a repository of user contributed code that can be relied on to meet some standard of functionality, reliability, usability, etc. Versus the OBEX, which is just code. The GS would have to therefore include more than just formating, as formating in no way garantees functionality.
As heater points out, Git Hub has the full spectrum of projects from "magrinal, does not work" to "excellent, does what it says". The marginal projects are contributed by anyone. The excellent projects are contributed by skilled engineers that exhibit discipline in specific behaviors. If something does not work with the current verrsion, a well crafted project can be maintained.
The specific behaviors characteristic of excellent projects tend to be something along the lines of clear requirements, thorough testing, and thoughful coding; to varying degree per specific project. Other engineers can follow, and understand, and contribute; and the work improves. Each behavior discipline evolves "better".
The issue is that most engineers in non regulated industries evolved these behavior unconsciously over years, and do not have an easy way to communicate what these behaviors are and how we do them. The "gurus" just "do their magic" and the rest of us can only struggle to keep up.
Process gives us a way to transfer knowledge from one crop of engineers to the next, through common terminology and organization. We can make "checklists" so "another set of eyes" can check if we missed something, or affirm that we have all our ducks in a row. Process allow us to train the next crop of engineers in the beneficial habits, and to avoid the detrimental habits, and to make these evaluations based on specific data.
In short, we can check each others work. Anyone can understand and participate, and we doen't have to overload a few key players.
The alternative to process is to learn the hard way, and fight the tide. We have to wait years for individuals to cvome up to speed. The hard way appears easier, but in the both the long and short run, it is expensive and ineffective. The process way appears to be more work, but process is simply pre-organized. Appropriate process is always the easiest way. Resistance is due to experience with inappropriate process.
Process is well established in manufacturing, is most established in electronics, and is still brand new in software. The goal here, then, is to transfer this knowledge down the technology curve from the very expensive, bleeding edge slope of the curve to the low tech, everyday, flat part of the curve.
This task of establishing a process for qualifying contributions to a Gold Standard Repository is not trivial, but it is not hard. Like anything in this life, it takes practice and refinement.
Anybody interested in thinking this through? Not as a commitment, just as a though exercise.
One of the beautiful features of the Propeller and Propeller II is the "soft peripheral" and all that goes with it. If Parallax is going to pursue a more professional oriented stance, then there needs to be a set of Parallax approved, vetted and supported soft peripherals for the Propellers. For any common peripheral offered as a hard peripheral on a competing architecture, there needs to be an equivalent soft offering from Parallax found in a Parallax software library. The answer can't be "Mr./Ms. Engineer, browse through the OBEX and see what you can find." That may be an option offered but the first and official answer needs to be "If you need a <insert standard here> driver then use this." It becomes the equivalent of the reference circuit in an application note. There needs to be a library that is proven code that provides a solution to a peripheral need just like a hard peripheral would.
Whether it's the FE group, the Product Manager or some other Parallax person, it needs to be a Parallax source that says and provides what is considered golden. Yes, this is a Parallax resource that is taxed, yes this is an expense but to me it's as much a cost of launching Parallax Semiconductor as getting the tools out there or anything else related to the P2 launch and the Parallax Semiconductor fist steps.
I can't imagine any chip manufacturer telling a corporate customer to go out and browse through the forums to see how others have hooked that chip up, there's some out there that should work pretty well for an application like yours.
I'm not a professional engineer, so pick this apart if you are but to me that isn't the way to go after professional clients and get your chips into their hands for evaluation purposes. I don't see browsing through the OBEX as a productive use of an engineer's time. I'd want to grab the applicable application note and the code that goes with it and start evaluating.
Take a look at Cypress's PSOC5 line, for each virtual peripheral there are detailed data sheets associated with them. It would be nice to see such documentation and support from Parallax.
http://www.cypress.com/?id=2233&rtID=377
Its both good and bad to see what has happened in the interim. Lots and lots of good discussion, however overall a failure to execute much, for several reasons.
If P-S does want to make any sort of significant entry into the more industrial realm, I would suggest that someone like Ken needs to take ownership of the effort, and make it a mission of his to bring to reality. Which I note, he did seem to do in his response above.
There seems to be several different standards at work on the net right now. The first is release what you have, when you have it, publish first and publish often or some such. This way you can get it out to the public and garner feedback while you are busy correcting bugs and features.
The other option is the Carmack-style 'We'll release it when its done, and not before'. This option shoots to release a product that is solid, and relatively bug-lite for better consumer satisfaction.
Both options have benefits and drawbacks which can be discussed at length and provoke navel-gazing.
Obviously for a business like P-S, one would think the Carmack-style option is preferred, as the target market is serious business(tm) types, and in reality many engineers are not quite as interested in adding software object troubleshooting to their own software writing work.
On the enthusiast side of the house, a more relaxed publish-first could easily work, with the OBEX/community refining objects over time to a more golden state.
While I'm not positive on where/why the GSL stalled, I would humbly suggest some possible avenues to re-igniting the GSL.
1. Ken needs to decide which GSL Design philosphy he want to push, quantity or quality.
2. Irrespective of which of the above is chosen, get a simple GSL interim documentation standard out to the community. I would hope most GSL's could be distilled down to the bare essence for now. Autodocs, and extensive notes from the originator on the ins-outs of how his software works are great, and would be invaluable to an engineer looking to double-check an object or modify it, however not necessary at this time. Sample GSL might be a barebones, fast term server, options for speed, duplex, start/stop bits and thats it. There could be another GSL term server which has those standard options, plus numerous others someone thinks would be good. However most engineers are probably going to be looking for objects that are fast and compact.
3, Ken/Parallax are always free with samples and stuff, so why not use the recent, nice, Forth Challenges as a model for the GSL?
Why not have a Challenge for the top 5 soft-peripherals thought to be needed by any engineer considering the Prop/Prop II? Not sure what those are, well why not set up a poll?
The main thing is to utilize the community, and currently the Challenge angle seems to be pretty popular to forum dwellers. Heck, you could probably make special avatars or honorable mentions for winners, consistent contributors. Doesn't always have to be a physical prize, though those are certainly helpful. Heck, why not give the Gold,Silver, Bronze winners of the above hypothetical challenge some free boards of their own layout? I don't know who/how you get your boards, however since you probably get panels by the dozens, you might be able to tack some on one run for close to free.
Just my two cents worth, I'm still working my way through the excellent audio podcast series so I don't want to come across as putting down anyone's efforts to date.
Its just that the Prop's primary selling point aside from interrupt-free is the concept of soft-peripherals in place of silicon. As mentioned by again by Mindrobots, Parallax and Parallax-Semi needs to show that it is serious by having numerous bullet-proof code objects for the prospective client to look at and work with prior to them ever making a serious decision on whether its worth the capitol or employee's time investment.
In regard to your #3, that was tried in is thread: http://forums.parallax.com/showthread.php?137491-Gold-Standard-Objects-Up-for-Commission&highlight=Gold+standard
I think it ended in a debate about the standards without a lot of volunteers actually writing objects. It's hard to muster a volunteer army around an effort like this. The products offered as bounties are great but as a volunteer force, it's easy to get distracted by the next shiny thing, especially when your day job doesn't allow distraction.
It's a tough line to walk between community involvement and internal development. At some points in this process, Parallax needs to just lay down the law and drive things internally and take the riisks to make it happen. Confusingly, when I start feeling this way, I see the successes and benefits of efforts like Chip's release of the FPGA code to allow customers to run the P2 emulations. Good stuff, there!!
Maybe there isn't an easy model to follow. I don't know, I've never done this before, either!
Early on, we had that with the core set of objects produced by Parallax. In some ways, those were non-optimal and that happened because we all contributed over time leading to alternatives. The interesting part about that was quite a bit of development centered around that nugget of useful code. Over time, much of it was replaced and in the replacing lots of competing ideas came along for the ride, sometimes working in lean ways with the originals, but often not.
And to be really clear and fair, it isn't a fault that happened. It just happened because everybody was working on stuff and shared code.
On that note, sharing code, I've always thought it good to have more of the objects work together, but I've also thought that gets in the way of making stuff work too. Some of us build on this stuff for entertainment or to build skill or complete projects we enjoy. That ranges from basic learning through hobby and into some professional uses. Others take it up a notch making a living related to Propeller chips and that ranges from incorporating them into the job scenario whatever it is, could be product design like the "Kill O Watt", or just service maintenance of custom systems, to feeding the market place with products designed to be part of other products, like the Gadget Gangster, or some of the things Bill Henning and Saphia did together.
These are a lot of conflicting uses!
And there is the sharing of code issue too. I myself contributed good code early on, but it really wasn't well realized in terms of general use. Later efforts got better and sometimes that all varied too. The variances come down to priorities, completing projects, available time, desire to do new vs maintain the old, and so on...
That means we can either encourage people to contribute code no matter what it looks like, or we can limit things and put requirements in front of them. Frankly, I want the code, good, bad, ugly. Many objects have some good routines in them that people can really use, but they might not be formatted optimally for "dropping in" like we all want, and that varies just because how we write stuff. How our code needs to connect to object code can and will vary and it will do so for good reasons more than not too. Often, it's easier to take the closest object and fix it to drop in than it is to author a brand new one, so that is a gain.
Isn't that gain very similar to having to sort out how to use the built in hardware on other devices? I think that is true a lot of the time. Maybe not all of the time.
Additionally, we've not really scratched the surface of editing MIT code. Somebody could post up a good object and somebody else could get it to work more generally too. The current OBEX isn't really structured for that, but something like Github is.
In summary:
People are going to do what they do, unless they are paid, or there are synergies that encourage them to do otherwise.
Sharing code --even if it's messy code is always good. The more code, the merrier. With that comes good tools to identify, promote and encourage people to take that code and make it better code whether or not they authored it.
The current OBEX isn't optimal. That led to another serious meta-discussion with some just wanting better repository functions to others wanting a lot of structure like the Perl CPAN, for example.
We need a body of code for people to gravitate to. This body just needs to work consistently and well, not be the perfect solution by committee.
Too much complexity and structure just won't work, unless there are very strong incentives. If the tools are flexible and robust and encourage sharing, editing, building, revising, referencing, linking, etc... then the good stuff will bubble up to the top organically, yet we don't lose the core work that gets us to that good stuff.
Finally, people like to be a part of something or contribute to something. If it's there and working, they can follow along and others can help out. Too many up-front expectations are real work, and again that means denying people the fun hobby time. This is precisely why I didn't contribute to the effort at all. When I have Prop time, the very last thing I want to do is spend it on the little details I would be required to do at work. Who does? And that's a core problem, leading to the summary I put here.
I would move to a better repository so that we can fork, revise, etc... with some history and ability to "undo" on a basic level so that things don't ever get lost or corrupt, other than that, yeah! I basically think the gold standard is whatever core nut of good code attracts people, and getting one funded might help guide things a little, though I would not do that right now with P2 cooking. Parallax has gotta get that done. But afterword? Totally.
Agreed, and I'm a big believer in always sharing code where possible. We can always sort it, tag it, prioritize it, combine it, whatever.
I started with it about 3 years ago, however I still remember some frustrations while starting.
The number one reason for choosing the Propeller was that it was multi-core, being the trend of modern systems it was a cool and fun thing to learn. But what I didn't realize was that many of those precious cores would be dedicated to re-invent the basic wheels an engineer needs (UART, SPI, ADC, etc). That was my fault, I know, it's just that it looks an overkill for me to waste a core for something so commoditized.
So unless you need an interface that's propietary, building you own wheels doesn't appeal to the typical engineer.
One other thing that I would have found great at the time is a recipe book style for the newcomer to the propeller that addresses the typical needs (want UART? Do this. Need XBee in API mode? Use this, etc) So a clear gold library of efficent and straightforward modules is of invaluable help to get up to speed.
Another thing besides golden modules is a series of application notes that cover the integration aspects of these modules in a non-trivial example that helps to visualize the power and flexibility of the Propeller, and also it's reasonable limits and approaches to overcome these. Kind of a "Propeller for non-parallaxians". Some work has been done on this which is an excellent starting point.
One key point to cover here is "How to debug your Propeller based system" with different options depending on what you have available (just serial, scope, logic analyzer, viewport, PASD, etc). This helps the engineer in getting up to speed, specially since we don't have a comprehensive source level debugger)
Just my two cents on this willing to contribute to Parallax's success.
Alex
The thing is, we're back to arguing about SVN vs Git vs word docs.
Why not avoid that mess for know, and focus on the actual objective, objects?
What are the 5 must-haves that any serious engineer/developer is going to expect to find on a modern uC, and what do we have that is software only that can compete?
One can argue that, however the value proposition of the Prop is that it doesn't include them 'because' they can be done in software.
Meanwhile, I'll just start a thread asking for input on the 5 'must have' objects the Prop would need to convince the average engineer. If there is enough input, and suggestions, maybe a poll afterward, or Ken could get a decision from Parallax' perspective.
About the only thing I said on this was the current OBEX really isn't adequate for efforts like this to form and grow, that's all, and I could be proven wrong on that too. Well, and I said that for it to take off there needs to be a set of objects all written to work well together with a minimum of glue code and debugging required, similar to the core set released by Parallax with the P1.
Whoever does this will establish the Gold Standard by simply having done it! Others can adopt it as they see fit and that's really all about the value of the package as opposed to whatever methods they are using now and their own library code built up over the years from the current pool of objects. If somebody wants to do it differently, they can fork the thing and have at it. If the current author walks away, others can pick it up, or do something different, etc... Additions and such make best sense when integrated into the current Gold body of code too, and that's where having a repository that helps to make that happen easily makes a lot of sense. Not telling anybody that should happen, but I am suggesting it's a great path, and one that I would follow, given the core set of objects make good sense.
Additionally, I know I'm not going to author the core code, but I may well choose to add to it in an area of interest and where a project makes sense to do that, meaning I would welcome any such effort where doing that is easy to do and robust.
Whatever repository and naming scheme they build on will be the "right" one too, because that is where the mind share will be and unless something really ugly is selected, it will generally be easier to adopt that scheme and build on it than not.
Without some central authority, we are a group of peers. That's how peers work.
I strongly agree with the core focus suggestion of objects. Great first move! They can be put somewhere, and that's a very nice problem to have.
To that end I would say the first rule for admission to the Gold Standard is:
0) IP blocks shall be written in C and/or PASM and usable from C. (If your PASM parts can be used from Spin, Forth, whatever that is a bonus but don't shout about it)
Corporate customers are mostly going to turn the page in the catalogue when they start reading about Spin objects.
Note I said IP blocks there. Avoid the use of the word "objects" it is very misleading. In the FPGA world they offer "IP blocks" to provide functionality like UARTs and such. In the software world they are "libraries" or "modules". "objects" has a whole lot of connotations about object oriented programming.
Another rule is:
1) Let's call "COGs" "cores" so that everyone instantly knows what you are talking about. Let's call "HUB RAM" just "RAM" or "shared RAM" so that no one has to scratch their head wondering what a HUB is.
2) Provide decent data sheets for each such IP block/modules. Think how Intel sold a processor and a family of chips for UARTS, Timers, PIO, etc. each with a comprehensive data sheet. The Prop has such functionality but without the silicon, it still needs the data sheets.
3) The IDE should allow browsing of such modules and dropping them into a project with a click, perhaps with some configuration dialogue. Much the way you drop a multiplier IP block into an FPGA design for example.
In short, be "normal":) Present things in a way that people can connect to immediately.