We are in serious need of comprehensive documentation. That might evolve to perhaps a user's guide, a programmer's guide, an operator's guide, a reference manual, etc. Sure we are a long way off from needing all of those, but the current Github READMEs do not scale well for even one of those.
The next option is the Wiki. A Wiki could provide a centralized source for the comprehensive documentation mentioned above. Unfortunately, a Wiki will just not scale as our project matures for a few reasons. (1) It is much more likely that we will keep the docs up-to-date if the code and documentation co-exist and are versioned together. For example, we can ensure that the docs are updated at the same time that code is changed as part of a single PR. If there is no documentation, then there is no +1. (2) We need a tool that will allow multiple versions of the documentation to co-exist; just like the code. There will soon be be multiple versions of Metron in use, in the wild. Users will need access to docs for the specific version they are using. This is rather difficult to do with a Wiki. (3) We need a tool that allows us to publish the documentation in multiple formats. I may want to publish the documentation on the web, as a PDF, or even include the docs within a Metron release tarball. This is flexibility that we don't have with a Wiki. (4) The controls provided by Git/Github are just more flexible and powerful than what is provided on the Apache Wiki platform. Right now, only a few individuals can edit the Wiki. And those users can change anything without peer review. This will not scale as the community grows. We need something like Mkdocs. Maybe there are alternatives out there that are better. We really need something like it though. I'm open to alternatives. On a side note, it seems like I run across tons of projects using Mkdocs. Once I started recognizing the basic Mkdocs templates, I started recognizing all the projects using it. On Tue, Jul 5, 2016 at 6:25 PM, James Sirota <[email protected]> wrote: > Nick, > > What is the advantage of Mkdocs over the Wiki or Github readme? > > Thanks, > James > > 05.07.2016, 08:30, "Nick Allen" <[email protected]>: > > FWIW, I think it would be great to use Mkdocs [1] to create centralized > > documentation that we keep managed under source control. We can then use > > Mkdocs to publish a version of the documentation for each release. > > > > [1] http://www.mkdocs.org/ > > > > On Sun, Jul 3, 2016 at 10:38 PM, Waterson, Kevin < > > [email protected]> wrote: > > > >> Awesome, > >> > >> I will begin with installation, following the existing docs at > >> https://cwiki.apache.org/confluence/display/METRON/Documentation > >> > >> Anything which is missing I will be able to flesh out, and other docs > can > >> be created as I become more familiar with the application. > >> > >> Kind regards > >> Kevin > >> > >> -----Original Message----- > >> From: Nick Allen [mailto:[email protected]] > >> Sent: Thursday, 30 June 2016 10:16 AM > >> To: [email protected] > >> Subject: Re: Introduction > >> > >> Looking to help with documentation? How lucky are we! We need a lot of > >> help in this area. > >> > >> We have some level of documentation dispersed in READMEs embedded in > the > >> code base and more in the Metron Wiki. Bringing it all together somehow > >> would be a vast improvement. > >> > >> Welcome Kevin > >> On Jun 29, 2016 4:49 PM, "Waterson, Kevin" < > >> [email protected]> > >> wrote: > >> > >> > Hi all, > >> > New to metron and hope to get involved in documentation at some time. > >> > > >> > Currently working with larger telco in southeast asia region. > >> > > >> > Looking forward to contributing. > >> > > >> > Kind regards > >> > Kevin > >> > > > > > -- > > Nick Allen <[email protected]> > > ------------------- > Thank you, > > James Sirota > PPMC- Apache Metron (Incubating) > jsirota AT apache DOT org > -- Nick Allen <[email protected]>
