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
