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

["Matt Foley (JIRA)" <ji...@apache.org>]

Matt Foley created METRON-660:
---------------------------------

             Summary: [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


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 gathers the README.md files from all code subdirectories into a hierarchical list.  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.

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.4#6332)