That's exactly right and I'm game for any of your suggestions. My preference would probably be either examples.md for each module, or an examples folder with a list of .md files named for the specific feature example under each module, as you discussed.
There has been some recent discussions on the user mailing list specifically around the idea of better documentation in the way of examples and explanations. This will take a while to put together, but I'd be happy to start working on it, starting with a migration and double check of existing documentation. I'd love to get more opinions on the idea, if possible. Jon On Mon, Mar 6, 2017 at 1:55 PM Michael Miklavcic < michael.miklav...@gmail.com> wrote: > Just to clarify the point about migrating from the wiki - you'd like to see > use cases, demos, cookbooks, etc. moved into the git repo? I'm +1 for this > as it allows us to version the examples with each commit and release. A > feature that is currently lacking and more difficult to accomplish on the > wiki. We could always link the wiki and/or Metron website to the latest > master branch for up to date examples. I'd like to give people more avenues > to access information than less, but definitely do not want to duplicate > docs. > > I think it also makes sense to me to keep the examples closer to the code. > As a compromise between project root level vs package level, I think > keeping an examples folder within each Maven module seems reasonable to me. > Examples.md seems ok. We might even choose to create a folder for examples > and name the md file by feature. Or we could create sub-folders naming the > feature and drop examples.md files in each folder. I'd also like to > include > the concept of "cookbook" examples here as well. I think there is overlap > with demos and use cases, but cookbook examples can often be more specific > to a fine grained task. > > Mike > > > On Mon, Mar 6, 2017 at 7:02 AM, zeo...@gmail.com <zeo...@gmail.com> wrote: > > > bump > > > > On Sat, Feb 11, 2017 at 2:15 PM zeo...@gmail.com <zeo...@gmail.com> > wrote: > > > > > This morning I had an opportunity to watch the video from yesterday's > > > community demo, and there was some really good discussion towards the > end > > > about documentation of examples that I wanted to follow up with. For > > > future reference, here<https://www.youtube.com/watch?v=oElf7G_m7_E> is > > > the recording of what I'm referring to - this is all as a follow-up to > > > Matt's great work via METRON-660 > > > <https://issues.apache.org/jira/browse/METRON-660>. > > > > > > I am looking for feedback on an idea for the future of Metron > > > documentation. At a high level, I would like to migrate materials from > > the > > > wiki pages throughout the git repo and modify our documentation > > generation > > > scripts to key in on tutorials vs readmes. Once we have agreement on > > this > > > I would be happy to handle any data migration and manipulation as > > necessary. > > > > > > More specifically, I would like to establish a convention for the names > > of > > > example or tutorial md files that we could then use when generating the > > > release documentation. Say we use "examples.md", we could then > generate > > > an examples/tutorials top level area in the site-docs without having to > > add > > > it into the git repo itself. In addition, this lets the examples.md > > > files exist more closely to the code they are about, which seems to be > > the > > > preference of most people currently working on the project. > > > > > > A good example of this would be to break Casey's outlier analysis > example > > > <https://github.com/apache/incubator-metron/tree/master/ > > metron-analytics/metron-statistics#outlier-analysis> > > > into a new examples.md in the same directory. I would think more > > > generalized examples/tutorials would exist in the root of the git repo. > > > I'm also game for arguments that we take another approach, such as > > making a > > > new top level folder in the repo for all examples/tutorials, but that > > would > > > be less preferred in my opinion. > > > > > > We could probably move the overview > > > <https://cwiki.apache.org/confluence/display/METRON/Metron+Wiki>, > > > architecture > > > < > https://cwiki.apache.org/confluence/display/METRON/Metron+Architecture > > >, > > > tutorials > > > <https://cwiki.apache.org/confluence/display/METRON/Documentation>, > and > > > governance > > > <https://cwiki.apache.org/confluence/display/METRON/Apache+Governance> > > > wiki materials without much of an issue. Pages like the tech talks > > > <https://cwiki.apache.org/confluence/display/METRON/Tech+Talks> and > > > community > > > <https://cwiki.apache.org/confluence/display/METRON/Metron+Community> > > information probably > > > fit better in the Metron site > > > <https://github.com/apache/incubator-metron/tree/master/site> area of > > > GitHub, and not as a md. The items that I wouldn't be sure about > > migrating > > > are things like the user research > > > <https://cwiki.apache.org/confluence/display/METRON/User+Research> or > > meeting > > > notes < > https://cwiki.apache.org/confluence/display/METRON/Meeting+notes > > >. > > > Is there still value in having these materials published? Maybe we > leave > > > them behind in the Wiki and use it as more of an archive store for > > > historical context? > > > > > > If I don't get any strong disagreement with this idea, I'm going to > throw > > > together a first attempt. I also opened a ticket for this - METRON-714 > > > <https://issues.apache.org/jira/browse/METRON-714>. > > > > > > Jon > > > -- > > > > > > Jon > > > > > > Sent from my mobile device > > > > > -- > > > > Jon > > > > Sent from my mobile device > > > -- Jon Sent from my mobile device
