Add documentation entries for the second quarter status report.
This commit is contained in:
Warren Block
parent
e6b9686b36
commit
c89c7cece2
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=46950
1 changed files with 104 additions and 0 deletions
|
|
@ -83,4 +83,108 @@
|
|||
<description>Miscellaneous</description>
|
||||
</category>
|
||||
|
||||
<project cat='doc'>
|
||||
<title>New Documentation Committers</title>
|
||||
|
||||
<contact>
|
||||
<person>&os; Documentation Engineering Team</person>
|
||||
<email>doceng@FreeBSD.org</email>
|
||||
</contact>
|
||||
|
||||
<links>
|
||||
<url href="https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/">&os; Porter's Handbook</url>
|
||||
<url href="https://www.freebsd.org/">&os; Web Site</url>
|
||||
<url href="https://www.freebsdfoundation.org/">&os; Foundation Web Site</url>
|
||||
</links>
|
||||
|
||||
<body>
|
||||
<p>Two new documentation committers were added to the team in
|
||||
the second quarter of 2015.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>Anne Dickison is Marketing Director for the &os; Foundation.
|
||||
She will focus on updating and improving the &os; main web
|
||||
site.</p>
|
||||
|
||||
<p>We welcome both new committers and look forward to their
|
||||
contributions!</p>
|
||||
</body>
|
||||
</project>
|
||||
|
||||
<project cat='doc'>
|
||||
<title>Documentation Working Group at BSDCan</title>
|
||||
|
||||
<contact>
|
||||
<person>&os; Documentation Team</person>
|
||||
<email>freebsd-doc@FreeBSD.org</email>
|
||||
</contact>
|
||||
|
||||
<links>
|
||||
<url href="http://www.bsdcan.org/">BSDCan</url>
|
||||
<url href="http://docutils.sourceforge.net/rst.html">reStructured Text</url>
|
||||
<url href="http://daringfireball.net/projects/markdown/">Markdown</url>
|
||||
<url href="http://asciidoc.org/">AsciiDoc</url>
|
||||
<url href="https://wiki.freebsd.org/">&os; Wiki</url>
|
||||
<url href="https://www.freebsd.org/">&os; Web Site</url>
|
||||
<url href="http://annotatorjs.org/">Annotator</url>
|
||||
<url href="https://github.com/openannotation/annotator/wiki#backend-stores">Annotator Backend Stores</url>
|
||||
</links>
|
||||
|
||||
<body>
|
||||
<p>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.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<p>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.</p>
|
||||
</body>
|
||||
|
||||
<help>
|
||||
<task>
|
||||
<p>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.</p>
|
||||
</task>
|
||||
</help>
|
||||
</project>
|
||||
|
||||
</report>
|
||||
|
|
|
|||
Loading…
Reference in a new issue