Re: [PROPOSAL] up-to-date versioned documentation

This is fantastic. Great job, Matt 29.01.2017, 22:13, "Matt Foley" : > Hi all, please take a look at > https://github.com/apache/incubator-metron/pull/429 > I think all major issues are resolved, as best I can tell from an eyeball > scan of the result. > Thanks, > --Matt > >

Re: [PROPOSAL] up-to-date versioned documentation

Hi all, please take a look at https://github.com/apache/incubator-metron/pull/429 I think all major issues are resolved, as best I can tell from an eyeball scan of the result. Thanks, --Matt On 1/19/17, 12:06 PM, "Justin Leet" wrote: Yeah, this looks like a huge

Re: [PROPOSAL] up-to-date versioned documentation

Yeah, this looks like a huge leap forward, and I'm thrilled that you made such good progress. Great job, Matt. On Thu, Jan 19, 2017 at 1:55 PM, Michael Miklavcic < michael.miklav...@gmail.com> wrote: > Agreed! Matt, thanks for taking this on and glad I could help. > > M > > On Thu, Jan 19, 2017

Re: [PROPOSAL] up-to-date versioned documentation

Agreed! Matt, thanks for taking this on and glad I could help. M On Thu, Jan 19, 2017 at 11:42 AM, Casey Stella wrote: > Oh wow, I really like the looks of that. I was skeptical before, but if > you got that far in a couple of days, I think this is a worth-while >

Re: [PROPOSAL] up-to-date versioned documentation

Thanks, Jon! I’m working on characterizing exactly how to fix the two main issues. I think I’ve got a script that will auto-fix the triple-backtick problem. The bullet list problem will require hand-editing, so I want to make sure I’ve got the right recommendation. The larger issue is going

Re: [PROPOSAL] up-to-date versioned documentation

Looking at the screenshot, that would be an incredible improvement on what we currently have. I'd be happy to help out with any markdown modifications and documentation cleanup, if necessary, to fix the problems you outlined above. Jon On Thu, Jan 19, 2017 at 11:22 AM Matt Foley

Re: [PROPOSAL] up-to-date versioned documentation

Not seeing the attachment, is it attached to a jira? On January 19, 2017 at 04:19:02, Matt Foley (ma...@apache.org) wrote: Here’s a screen shot, attached :-) On 1/19/17, 1:04 AM, "Matt Foley" wrote: Hi all, I’ve put together a prototype doc book, along the lines we

Re: [PROPOSAL] up-to-date versioned documentation

Hi all, I’ve put together a prototype doc book, along the lines we discussed, and it looks pretty worthwhile. Many thanks to Mike M. who whipped the pom.xml file into shape, and helped me find the right site.xml file to imitate. If you’re interested, please do a single-branch clone as follows:

Re: [PROPOSAL] up-to-date versioned documentation

Hey Matt, feel free to ping me. On Mon, Jan 16, 2017 at 1:39 PM, Matt Foley wrote: > I looked into the Falcon website and doxia over the weekend, and I’m > convinced that using the doxia-markdown plugin should make it dirt simple > to do what’s been discussed in this thread,

Re: [PROPOSAL] up-to-date versioned documentation

I looked into the Falcon website and doxia over the weekend, and I’m convinced that using the doxia-markdown plugin should make it dirt simple to do what’s been discussed in this thread, with no overhead on the part of people writing the README.md files. I fiddled with trying to do a POC, and

Re: [PROPOSAL] up-to-date versioned documentation

+1 I think it is sorely needed. If we can come up with a really slick solution like Spark, then great. I am also not against a half-baked solution that can later evolve into something else. For example, create an index README.md that links together all the existing READMEs and run Pandoc on it.

Re: [PROPOSAL] up-to-date versioned documentation

I think something that does what you have laid out here, no matter the implementation details would be ideal On January 12, 2017 at 18:05:24, Matt Foley (ma...@apache.org) wrote: We currently have three forms of documentation, with the following advantages and disadvantages: || Docs || Pro ||

Re: [PROPOSAL] up-to-date versioned documentation

The Spark docs sure are pretty. I suspect there’s a lot of person-weeks of work behind the content. I don’t know how hard it was to set up the infrastructure, but the instructions for generating the site mention an impressive list of tools needed. The Falcon docs site seems much more

Re: [PROPOSAL] up-to-date versioned documentation

Matt, thanks for pulling this together. I completely agree that we need to go all in on either cwiki or the README.md's. I think the wiki is poorly updated and can cause confusion for new users and devs. My preference is certainly for the README.md's. I like your approach but also agree that we

Re: [PROPOSAL] up-to-date versioned documentation

Casey, Matt - These guys are using doxia https://github.com/apache/falcon/tree/master/docs Honestly, I kind of like Spark's approach - https://github.com/apache/spark/tree/master/docs Mike On Thu, Jan 12, 2017 at 4:48 PM, Matt Foley wrote: > I’m ambivalent; I think we’d end

Re: [PROPOSAL] up-to-date versioned documentation

I’m ambivalent; I think we’d end up tied to the doxia processing pipeline, which is “yet another arcane toolset” to learn. Using .md as the input format decreases the dependency, but we’d still be dependent on it. I had anticipated that the web page would be a write-once thing that would be

Re: [PROPOSAL] up-to-date versioned documentation

Just a followup thought that's a bit more constructive, maybe we could migrate the README.md's into a site directory and use doxia markdown (example here ) to generate the site as part of the build to resolve 1 through 3? On Thu, Jan 12, 2017 at

Re: [PROPOSAL] up-to-date versioned documentation

So, I do think this would be better than what we currently do. I like a few things in particular: - I don't like the wiki one bit. - We have a LOT of documentation in the README.md's and it's sometimes poorly organized - I like a documentation preprocessing pipeline to be present.

[PROPOSAL] up-to-date versioned documentation

We currently have three forms of documentation, with the following advantages and disadvantages: || Docs || Pro || Con || | CWiki | Easy to edit, no special tools required, don't have to be a developer to contribute, google and wiki search | Not versioned, no review process, distant