The following outline is from the perspective of a non-doc-committer-committer who wants to see (our good) documentation get 10x better.

===== Problem Definition =====

  * Docs in %%FreeBSD%% is hard^W not (or doesn't appear) easy/simple enough.
  * Docs are in XML (%%DocBook%%) format. This doesn't suit humans.
  * Docs is a separate, repository-specific group of people.
  * Lots of apparent or perceived tribal knowledge required.
  * Process documented well, but super scary: looks super complex and overwhelming, even to existing committers

Finally:

  * First you have to get a commit bit, then you have to become (eventually) a docs committer. Translation: MUST be a docs committer to update docs without a chaperone.

===== Result / Current State =====

  * Too hard, don't try. New/regular (non-committer) contributors practically nonexistent.
  * Even easy stuff/changes don't get submitted
  * Bad user outcomes: Docs lag behind current state, often for a very long time
  * Burnout: Overburdened docs team

===== Goals =====

  * Zero-friction documentation authoring/updates. Ideally: Click 'edit', make changes. Save.
  * Non-committers submitting high quality docs updates
  * Docs issues in Bugzilla processed as well as Ports

Needs

  * As simple and easy as possible.
  * No unnecessary additional burden on docs/project: Well-maintained, not NIH.
    * I don't want to know what latex/docbook/bibliography are. At least not initially
    * I want to update/add docs, right now.
  * Focus on content not markup: Automatic formatting / validation
  * Proper use of docbook/freebsd docs features: Entity/Tag library/completion
  * Easy, single step installation: exists or could exist as a port/package 
  * Ideally improves the OSS ecosystem: %%OpenSource%%, if not free for %%OpenSource%% / Non-Profit Projects
  * Ideally multiple options/alternatives

===== Perspectives / Concepts =====

  * Docs as changing code. This is the //solution is an editor + svn integration// perspective. Checkout, launch program, edit, save, commit.
  * Docs as content editing. This is the //solution is a wiki/service// perspective. View, edit, save.

===== Tooling =====

==== Editors ====

| Name | Language | %%OpenSource%% | Free for OSS | Windows | Mac | Linux | %%FreeBSD%% | Port{s,able} | %%DocBook%% Support |
| [[https://www.oxygenxml.com|oXygen DocBook Editor]] | Java | ✘ | ✘ | ✔ | ✔ | ✔ | ✔ | ✔ | 4, 5, ?? |
| [[http://www.xmlmind.com|XMLmind DocBook Editor]] | Java | ✘ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | 4, 5, 5.1 |
| [[http://www.lyx.org|LyX]] | C++, Python, QT | ✔ | N/A | ✔ | ✔ | ✔ | ✔ | [[https://www.freshports.org/print/lyx/|print/lyx]] | ?? |

==== Applications ====

| Name | Language | %%OpenSource%% | Free for OSS | %%DocBook%% Support |
| [[http://www.xwiki.org|XWiki]] | Java | ✔ | N/A | 4.4 |

===== See Also =====

  * [[https://help.ubuntu.com/community/DocBookEditors|Ubuntu Wiki: DocBook Editors]]

===== Additional Notes =====

  * Web/App Translation. Mozilla Pontoon: https://github.com/mozilla/pontoon ([[https://pontoon.mozilla.org/|Production Service]])
  * Publishing. Mozilla Nucleus: https://github.com/mozilla/nucleus ([[https://wiki.mozilla.org/Websites/Mozilla.org/Publishing|Websites/Mozilla.org Publishing]])