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>
|
<description>Miscellaneous</description>
|
||||||
</category>
|
</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>
|
</report>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue