Versions Compared

Old Version 9

changes.mady.by.user gg2147@att.com

Saved on

compared with

New Version 10

changes.mady.by.user Matthew Harffy

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

CharacteristicProposed for ONAPExample from OPNFVCurrent ONAP & ExamplesOther Option or Examples
Documentation Source Repo Hostgerrit.onap.orggerrit.openfv.orgAll documentation is on the
wiki.onap.org as pages or
attached reference documents
in PDF form.  Wiki contains more
than release documentation

github.org

also could be sourced by gerrit or other git tools

Maybe we could create a onap.github.org

Documentation Source Repo Structure

/docs - Top level documentation index &
          select cross project content

/<any other project repo>/docs - documentation
           source created/maintained by a project
           that is integrated into the top level
           index and documentation for  release

sub-directories of both of the above reflect the
          documentation index hierarchy

Top Level


Example of one "other project"




Top level structure (sub-directories) include
templates, release, development, testing. 

Example other project provides (in sub-directories)
material for integration into "release" and "development"

Subset of the links on wiki.onap.org
eg. Using ONAP


Same
Source Format

Restructured Text

Comments (gg2147@att.com)

Pros

  • More Features (e.g. footnotes, tables, citations, tables of contents)
  • Standardized & Uniform spec
  • Fully extensible
  • Good for more robust documentation

Cons

  • Complexity = tougher to enforce adoption and consistency with developers? (Comment: Matthew Harffy - I think the structure is actually there to make it more consistent and enforcable)


Comments on editing tools: (Matthew Harffy)

Some example editors here: https://wiki.typo3.org/Editors_(reST)

I have looked at http://rst.ninjs.org/ - it is simple, but validates semantics on the fly and makes for quick editing. As an online tool, I could see issues with not having the content stored in a repository at the editing stage, or on a local machine.

The comments on https://notex.ch/ seem very positive, but I can't access it.

Top Level Index PageMultiple Requiring Commercial Software

Markdown

Comments (gg2147@att.com)

Pros

  • Well-known by Developers (e.g. Github / Stackoverflow)
  • Easy to learn, fewer features
  • Simplicity = easier to enforce consistency with developers?
    (Comment: Matthew Harffy - the simplicity could be a considered a con, as it makes it more difficult to enforce structure and consistency.)
  • Good for html on a single page (e.g. blogs, github descriptions,  comment boards, etc.)

Cons

  • Basic features may not be adequate for large scale projects
  • Not extensible, multiple "flavors" of Markdown in marketplace
  • No Semantic meaning - requires embedded HTML markup
Published DocumentationHTML, PDF, Epub for all documentation at
onap.readthedocs.io/en/latest/

http://opnfv.readthedocs.io/en/latest/

HTML or PDF depending on the
document or topic

HTML at github.org(no need to build)

other documentation by jekyll.

CI/CD FlowCommitter approved change merged to
doc or other project/doc repository branch
triggers a verify & build of published documentation.		Top level index reference to other project release notes
and creation of a composite source document set		Manually updated for a release
by collecting information from projects
eg. Release Notes 1.0.0 draft

For Markdown.

Committer approved change merged to doc or other project/doc repository branch, no building progres,

the webpage will be refreshed in seconds

For PDF or other form, same with RST.

CI/CD ToolsGerrit, Jira, Tox, Jenkins, Sphinx

Gerrit,Jira,

Jekyll.

No need any CI tools, just use the github.org to gerenrate a webpage.

Option SummaryOption 1Option 2
LanguageReStructured TextMarkdown



Site GeneratorSphinxJekyll
PublishReadTheDocsGitHub

Comparison for more Opensource Documentation Projects

...