Differences

This shows you the differences between two versions of the page.

--- devsummit:201210:documentation [2012/08/20 20:50] – Add Gabor BenedictReuschling
+++ devsummit:201210:documentation [2021/04/25 07:56] (current) – Fix DevSummit links. JethroNederhof
@@ Line 1: / Line 1: @@
 //Note: Do not edit this page yourself unless asked to.//
-===== FreeBSD Developer Summit: Template Group =====
+===== FreeBSD Developer Summit: Documentation Working Group =====
-//(Add the exact date and time of your working group here.)//
+Friday, 19 October 2012, 9:00 - 12:30 (with a half hour break in between)
 ==== Overview ====
-This working group mainly focuses on trying to pick up what was left from the session at [[http://wiki.freebsd.org/201205DevSummit/Documentation|BSDCan's DevSummit]] and the combined BSDCan/PGCon doc summit and continue what actions and solutions have been identified there as well as new things that came up in the meantime.
+This working group mainly focuses on trying to pick up what was left from the session at [[DevSummit/201205/Documentation|BSDCan's DevSummit]] and the combined BSDCan/PGCon doc summit and continue what actions and solutions have been identified there as well as new things that came up in the meantime.
 If you would like to participate, contact the working group chairs below and CC ''%%devsummit@%%''. You will be then added to this page. Please include a list of things you want to talk about or the areas you are interested in. This helps us in planning the session and to bring people together with common interests.
@@ Line 20: / Line 20: @@
 ^ # ^ Topic Description ^
-| XML %%DocBook%% conversion | It is either already there by the time %%EuroBSDcon%% happens or the conversion is still ongoing. Either way, it should be discussed what is left to do, like updates to the FDP primer and training of our doc committers to the new doc infrastructure based on XML. |
+| XML %%DocBook%% conversion | It is either already there by the time %%EuroBSDcon%% happens or the conversion is still ongoing. Either way, it should be discussed what is left to do, like updates to the FDP primer and training of our doc committers to the new doc infrastructure based on XML. We also have to think about depending on Java since the best free PDF renderer out is based on Java. |
-| Handbook print and electronic editions | Now that there is SVN with support for branches, the reorganization of the handbook into a publishable format (including but not limited to: the preface with all the changes since the last publicized version) could be started. Discuss what is the best format to do this and how to divide the work among those who are interested in seeing this happen. |
+| Handbook print and electronic editions | Now that there is SVN with support for branches, the reorganization of the handbook into a publishable format (including but not limited to: the preface with all the changes since the last publicized version) could be started. Discuss what is the best format to do this and how to divide the work among those who are interested in seeing this happen. Also, e-book readers should be well supported. |
-| Doc tools | Tools for documentation work, little helper scripts (like one for comparing revisions between translation projects and the en_US repo tree) should be talked about. Collecting more ideas for tools that we could create/use and distribute the work to make them available is one goal. |
+| Doc tools | Tools for documentation work, little helper scripts (like one for comparing revisions between translation projects and the en_US repo tree) should be talked about. Collecting more ideas for tools that we could create/use and distribute the work to make them available is one goal. Maybe is there any way we can have a customized IDE like Eclipse for easier document authoring? |
+| Old content | We should deal efficiently with old content. Wrong information is worse than no information at all. Possible ways of detecting outdated content and possible ways of marking outdated translations as such. |
+| UTF-8 encoding | We could achieve more uniformity by using UTF-8 all over the tree. Toolchain support and possible difficulties should be evaluated carefully before such a migration (e.g. editing docs in a terminal). |
+| Best practices | There are quite some non-standard ad-hoc scripts that generate pages. XSLT is based on templates (less error-prone and extensible) and nicely fits our XML infrastructure. Web pages contain scattered formatting elements and attributes, which should be ideally done globally by CSS. XHTML 1.0 Strict or a bit more constrained schema would avoid this. Document these and similar best practices in the FDP primer and assure it covers everything either by itself or by proper pointers. |
+| Profiling of Handbook | It is a constant problem that the base system changes and we have scattered information that only applies to older versions. Newer version of %%DocBook%% provide a feature - called profiling - that allows us to mark up specific parts as belonging only to one profile. We could thus mark up such parts and generate release-specific parts of Handbook or still generate the whole one. Such markup would also help us locating outdated parts when a major release reaches EOL. |
-//Note: General presentations about work you have done that does not require further discussions should be submitted for the %%FreeBSD%% Developer Summit track at %%EuroBSDcon%% (see [[/201210DevSummit|general developer summit]] page).//
+//Note: General presentations about work you have done that does not require further discussions should be submitted for the %%FreeBSD%% Developer Summit track at %%EuroBSDcon%% (see [[DevSummit/201210|general developer summit]] page).//
 ==== Attending ====
-In order to attend you need register for the [[/DevSummit|developer summit]] as well as by email for the session and be confirmed by the working group organizer.  Follow the guidelines described on the [[/201210DevSummit|main page]] or what you received by email.  For questions or if in doubt ask the session chairs.
+In order to attend you need register for the [[/DevSummit|developer summit]] as well as by email for the session and be confirmed by the working group organizer.  Follow the guidelines described on the [[DevSummit/201210|main page]] or what you received by email.  For questions or if in doubt ask the session chairs.
 Everyone interested in documentation is welcome to join. This includes doc committers and contributors, but we have also learned in the last sessions that sometimes ports, src and even infrastructure people can provide valuable insights into problems the doc people scratch their heads about far longer than necessary. So a mixed audience is welcome, but we will also try to keep the number of attendees small enough to be productive.
-**Please do NOT add yourself here.** Your name will appear automatically once you received the confirmation email. You need to put your name on the general [[/201210DevSummit|developer summit]] attendees list though.
+**Please do NOT add yourself here.** Your name will appear automatically once you received the confirmation email. You need to put your name on the general [[DevSummit/201210|developer summit]] attendees list though.
 ^ # ^ Name ^ Username / Affiliation ^ Topics of Interest ^ Notes ^
@@ Line 38: / Line 42: @@
 | 2 | [[/BenedictReuschling|BenedictReuschling]] | bcr |  | chair |
 | 3 | GáborKövesdán | gabor |  |  |
+| 4 | [[/ReneLadan|ReneLadan]] | rene |  |  |
+| 5 | [[/MichaelDexter|MichaelDexter]] | %%CallForTesting%%.org |  |  |
+| 6 | [[/GavinAtkinson|GavinAtkinson]] | gavin |  |  |
+| 7 | [[/TodMcQuillin|TodMcQuillin]] | spamcop.net |  |  |
+==== Notes ====
+http://openetherpad.org/Ybnfab21nI
 ==== Results ====
-//(Add a list or attach slides detailing the achieved results here.)//
+{{devsummit/201210/documentation/docwgeurobsdcon2012results.pdf?linkonly|Working Group Results Presentation}}
+----
+{{tag>Historical}}