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/%[email protected]%3E
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
