[
https://issues.apache.org/jira/browse/METRON-660?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15852506#comment-15852506
]
ASF GitHub Bot commented on METRON-660:
---------------------------------------
Github user mattf-horton commented on the issue:
https://github.com/apache/incubator-metron/pull/429
@JonZeolla you pushed my perfectionist button :-) This latest push fixes
the problem with anchors on H1 headers. The generated html is unchanged except
for the insertion of anchor lines next to H1 header lines. The visuals appear
the same.
> [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/%[email protected]%3E
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
