metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Zeolla@GMail.com" <zeo...@gmail.com>
Subject Re: [DISCUSS] Wiki use and migration of docs
Date Mon, 06 Mar 2017 14:02:21 GMT
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