[jira] [Commented] (METRON-660) [Umbrella] up-to-date versioned documentation

["ASF GitHub Bot (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/METRON-660?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15848045#comment-15848045 ] 

ASF GitHub Bot commented on METRON-660:
---------------------------------------

Github user mattf-horton commented on the issue:

    https://github.com/apache/incubator-metron/pull/429
  
    Okay, @JonZeolla , @justinleet , and others, the awk script has been replaced by a python script.  The results of the dialect fix-up are identical to the awk script's results across all 37 .md files.  Thanks.


> [Umbrella] up-to-date versioned documentation
> ---------------------------------------------
>
>                 Key: METRON-660
>                 URL: https://issues.apache.org/jira/browse/METRON-660
>             Project: Metron
>          Issue Type: Improvement
>            Reporter: Matt Foley
>            Assignee: Matt Foley
>         Attachments: METRON-660-screenshot2.png, site-book_0.3.0_20170130.tar.gz
>
>
> 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 from the code, obsolete content tends to accumulate |
> | Site | Versioned and reviewed, only committers can edit, google search | Yet another arcane toolset must be learned, only web programmers feel comfortable contributing, "asf-site" branch not related to code versions, distant from the code, tends to go obsolete due to non-maintenance |
> | README.md | Versioned and reviewed, only committers can edit, tied to code versions, highly local to the code being documented | Non-developers don't know about them, may be scared by github, poor scoring in google search, no high-level presentation |
> Various discussion threads indicate the developer community likes README-based docs, and it's easy to see why from the above.  I propose this extension to the README-based documentation, to address their disadvantages:
> # Produce a script that runs at build time and gathers the README.md files from all code subdirectories into a hierarchical tree.  The script would have an exclusion list for non-user-content, which at this point would consist of \[site/\*, build_utils/\*\].  
> # Utilize standard toolsets to publish the hierarchical collection of .md files as a "book", at least as far as the end user sees.  Put the web gateway for this book in the public Metron Site, preferably with a "version" pull-down menu that allows access to older versions too.
> # Deprecate the use of cwiki for anything but long-lived demonstrations/tutorials that are unlikely to go obsolete.  Move appropriate content from the cwiki into versioned .md files.
> Extensive email discussion of these ideas occurred in thread https://mail-archives.apache.org/mod_mbox/incubator-metron-dev/201701.mbox/%3C74A5A05B-B42D-482C-AE58-A0BE06770826@apache.org%3E



--
This message was sent by Atlassian JIRA
(v6.3.15#6346)