Details
-
Improvement
-
Status: To Do
-
Major
-
Resolution: Unresolved
-
0.3.1
-
None
-
None
Description
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.
Attachments
Issue Links
- relates to
-
METRON-718 integrate versioned site-book to public site (Metron home page)
-
- To Do
-