The code-level documentation should live in Github. Architecture and high-level documentation should live on the Wiki. The Wiki should be the entry point for anyone to get familiar with the project and should reference the Github docs for low-level details. This is the intent with the docs as they are structured currently.
Thanks, James On 4/26/16, 8:19 AM, "Nick Allen" <[email protected]> wrote: >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]>
