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

  • 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.
  • 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
  • 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
  • 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.
Name Language OpenSource Free for OSS Windows Mac Linux FreeBSD Port{s,able} DocBook Support
oXygen DocBook Editor Java ✘ ✘ ✔ ✔ ✔ ✔ ✔ 4, 5, ??
XMLmind DocBook Editor Java ✘ ✔ ✔ ✔ ✔ ✔ ✔ 4, 5, 5.1
LyX C++, Python, QT ✔ N/A ✔ ✔ ✔ ✔ print/lyx ??
Name Language OpenSource Free for OSS DocBook Support
XWiki Java ✔ N/A 4.4
  • kubilaykocak/docsng.txt
  • Last modified: 2016/08/26 17:22
  • by MarkLinimon