Great questions, Jon. I think these are standards that we need to define as a community.
Personally, I think maintaining documentation separate from code (aka the wiki) is bound to fail. If I change code, I need to be able to do a mass "find-replace" so that I update code and documentation at the same time. Code and documentation need to live side-by-side. On Tue, Apr 26, 2016 at 11:09 AM, [email protected] <[email protected]> wrote: > This morning I dug around on the website, github repo, and wiki to get > answers to what are some pretty standard FAQ-style questions. I've noticed > a few broken links along the way (On here > <https://cwiki.apache.org/confluence/display/METRON/Sensors>, this link > <https://github.com/apache/incubator-metron/tree/master/bro-plugin-kafka> > should be this > < > https://github.com/apache/incubator-metron/tree/master/metron-sensors/bro-plugin-kafka > >), > and also the fact that documentation sometimes exists in different places > depending on what you're looking at (For instance, in both README.mds > <README.mdshttps:// > github.com/apache/incubator-metron/blob/master/metron-streaming/Metron-EnrichmentAdapters/README.md > > > and wiki <https://cwiki.apache.org/confluence/display/METRON/Enrichments> > articles > <https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=62685647 > >, > etc.). > > I have two questions: > 1. Is there/should there be a standard location or method for how to > document, and where documentation exists? > 2. How can a user like me make sure they're looking in the right locations > for documentation, and when they find issues, submit the equivalent of a PR > to update it across the board (including on the cwiki). > > Thanks, > > Jon > -- > > Jon > -- Nick Allen <[email protected]>
