[
https://issues.apache.org/jira/browse/METRON-660?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Matt Foley updated METRON-660:
------------------------------
Description:
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
was:
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
> [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 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.4#6332)
