[
https://issues.apache.org/jira/browse/METRON-660?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15852323#comment-15852323
]
ASF GitHub Bot commented on METRON-660:
---------------------------------------
Github user mattf-horton commented on the issue:
https://github.com/apache/incubator-metron/pull/429
Hi @JonZeolla , you have good eyes! I missed those cases, which are only
visible where H1 headers have been used in the *body* of the document, AND
there are TOC or other internal links to those headings.
Eeesh, that's an unfortunate deficiency in the doxia-markdown plugin.
Apparently it does not generate named anchors for the H1 headers, perhaps under
the assumption there will only be one at the beginning of the doc? At any
rate, I've opened two new jiras:
- METRON-697 [site-book] doxia-markdown plugin doesn't generate named
anchors for H1 headings
METRON-698 [site-book] Add link checker as a "unit test" for site-book build
But I request that we allow these to be addressed as follow-on tasks, so we
can get the site-book as it is into the public's hands. 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/%[email protected]%3E
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
