From c89c7cece2baf616b42ab56ac6bd7ff20be4d137 Mon Sep 17 00:00:00 2001 From: Warren Block Date: Sun, 12 Jul 2015 01:28:52 +0000 Subject: [PATCH] Add documentation entries for the second quarter status report. --- .../news/status/report-2015-04-2015-06.xml | 104 ++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/en_US.ISO8859-1/htdocs/news/status/report-2015-04-2015-06.xml b/en_US.ISO8859-1/htdocs/news/status/report-2015-04-2015-06.xml index 215fa1c1fa..e4cd9a62b1 100644 --- a/en_US.ISO8859-1/htdocs/news/status/report-2015-04-2015-06.xml +++ b/en_US.ISO8859-1/htdocs/news/status/report-2015-04-2015-06.xml @@ -83,4 +83,108 @@ Miscellaneous + + New Documentation Committers + + + &os; Documentation Engineering Team + doceng@FreeBSD.org + + + + &os; Porter's Handbook + &os; Web Site + &os; Foundation Web Site + + + +

Two new documentation committers were added to the team in + the second quarter of 2015.

+ +

Mathieu Arnold is a member of the &os; Ports Management Team. + Over the past year, he has worked on many large and complex + updates to keep the Porter's Handbook current, and + continues to update this important document.

+ +

Anne Dickison is Marketing Director for the &os; Foundation. + She will focus on updating and improving the &os; main web + site.

+ +

We welcome both new committers and look forward to their + contributions!

+ + + + + Documentation Working Group at BSDCan + + + &os; Documentation Team + freebsd-doc@FreeBSD.org + + + + BSDCan + reStructured Text + Markdown + AsciiDoc + &os; Wiki + &os; Web Site + Annotator + Annotator Backend Stores + + + +

During the Developer Summit held in the two days before + BSDCan, a documentation working group meeting was held. We + discussed some of the biggest opportunities available to the + documentation team.

+ +

Modernizing our translation system was, again, a major topic. + Making it easier for translators to do their work is vitally + important. Translations make &os; much more accessible for + non-English speakers, and those people and the translators + themselves often become valuable technical contributors in + other areas. Progress was made in this area, and we hope to + have more news soon.

+ +

Methods of making it easier for people to contribute to + documentation was another major topic. At present, we use + DocBook XML for articles and books, and mdoc(7) for man pages. + These markup languages are not very welcoming for new users. + There are simpler documentation markup languages like RST, + Markdown, and AsciiDoc that take less time to learn and use. + In fact, these markup systems are all similar to each other. + These systems tend to be more oriented towards visual + appearance rather than the semantic markup of our present + systems, there might be ways to work around that.

+ +

Following the theme of making contributing easier, we also + discussed giving easier access so users can make additions to + the &os; Wiki. Like any other useful web resource, it was + horribly abused by spammers and access was limited to prevent + that abuse. It is tricky to allow submissions yet keep the + quality of submitted information usefully high.

+ +

Due to the markup systems used, it is difficult to review + documents for the quality of their information. Annotator is + a Javascript system that allows adding notes to an existing + web page. This would allow us to hold content-only reviews of + documentation web pages. Reviewers would not see markup, so + they could concentrate only on whether the information was + accurate and complete. To use this as desired, we need some + help with ports and testing.

+ + + + +

Complete a port for the backend storage component of + Annotator. Preferably this would be the lowest overhead and + most open-licensed version available. Assistance from those + familiar with Python and Javascript web development is + welcome.

+ + + +