Github user mmiklavc commented on the issue:
https://github.com/apache/metron/pull/530
Got it. Thanks @ottobackwards.
I want to repeat my appreciation for this contribution. I know it's taking
us time to get through review, and there's a lot of work in merging ongoing
changes, so thank you for being so patient and responsive!
I have some comments around the documentation as it stands. I love the
detail. This is probably more broadly and fully documented than many other
pieces of Metron. The only issue I see right now is that in order to know which
pages/READMEs are needed to add functionality requires the contributor to skim
through the full doc TOC.
I think it's still challenging to get a quick comprehension of the
extension/bundle/assembly/parser architecture with this README doc layout. The
subject separation is both useful and overwhelming at the same time. I want
users and contributors alike to get a quick sense of how to add general purpose
functionality, concrete OOTB core functionality, as well as their own custom
functionality. In order to even understand or know that these levels of
abstraction exist and then act on them, I found it necessary to read through
the entire doc structure to get a sense of things. For example, this is the
minimal set of docs a developer would need to read for managing
parsers/bundles/extensions, and I collected this list by clicking through every
link in the TOC.
- bundles-lib
- bundles-maven-plugin
- maven-archetypes
- maven-parser-extension-archeytpe
- extensions
- deployment
- packaging
- terms
- parser-extensions
- adding system parsers
- etc.
- parsers
- parser-testing
I think we should have an overarching document that ties all of these
components together cohesively from the perspective of extending Metron. The
mindset I'm taking here is very use case driven. I'm thinking something like a
document in the top-level of the project that covers "Extending Metron" and
then provides very clear overview and path for a soup-to-nuts new parser
stream. The outline might even look kind of like that list of projects outlined
above (but organized in order of operation), with links to the relevant
README's and an explanation of how it all fits together. A diagram like we have
for the topologies would also be extremely useful (at some point).
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
