DocsNG [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
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]])