I agree, I think all docs should be kept in the code base. I opened METRON-714 ages ago to get the existing cwiki docs over to READMEs as well.
I would also like to see us consider a more general/overview architecture, or perhaps write each component's architecture in a way that it can be composed into a higher level doc when generating the site-book. Right now the barrier to getting started with Metron is too high, and I think this would make it slightly less imposing. But this is slightly outside of the scope of the current conversation. Procedurally, do we have a way to ensure that any follow-on documentation happens prior to a release (anything in the wiki, etc.)? I'm fine with splitting the commits generally. Jon On Mon, Feb 25, 2019 at 8:50 AM Ryan Merriman <merrim...@gmail.com> wrote: > Recently I submitted a PR <https://github.com/apache/metron/pull/1330> > that > introduces a large number of changes to a critical part of our code base. > Reviewers feel like it is significant enough to document at an > architectural level (and I agree). There are a couple points I would like > to clarify. > > Generally architectural documentation lives in the README of the > appropriate module. Do we want to continue documenting architecture here? > I think it makes sense because it will be versioned along with the code. > Just wanted to confirm there are no objections to continuing this practice. > > A reviewer suggested we could accept the PR as is and leave the > architectural documentation as a follow on. I think this makes sense > because it can be tedious to maintain a large PR as other smaller commits > are accepted into master. An important requirement is the documentation > follow on must be completed in a timely manner, before the next release. > Are there any objections to doing it this way? > -- Jon Zeolla
