metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Miklavcic <michael.miklav...@gmail.com>
Subject Re: [DISCUSS] Wiki use and migration of docs
Date Mon, 06 Mar 2017 18:55:19 GMT
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, Zeolla@GMail.com <zeolla@gmail.com> wrote:

> bump
>
> On Sat, Feb 11, 2017 at 2:15 PM Zeolla@GMail.com <zeolla@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
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message