Jon Zeolla created METRON-714:
---------------------------------
Summary: Migrate documentation into git
Key: METRON-714
URL: https://issues.apache.org/jira/browse/METRON-714
Project: Metron
Issue Type: Improvement
Affects Versions: 0.3.1
Reporter: Jon Zeolla
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.
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 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, architecture, tutorials, and governance
wiki materials without much of an issue. Pages like the tech talks and
community information probably fit better in the Metron 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 or 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.
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
