devsummit:201210:documentation

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
devsummit:201210:documentation [2012/08/22 10:42] – Discussion topics for the working group, requested by bcr@ GáborKövesdándevsummit: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.// //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 ==== ==== 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. 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 26: Line 26:
 | 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). | | 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. | | 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|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. |+| 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 ==== ==== 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. 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 ^ ^ # ^ Name ^ Username / Affiliation ^ Topics of Interest ^ Notes ^
Line 42: Line 42:
 | 2 | [[/BenedictReuschling|BenedictReuschling]] | bcr |  | chair | | 2 | [[/BenedictReuschling|BenedictReuschling]] | bcr |  | chair |
 | 3 | GáborKövesdán | gabor |  |  | | 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 ==== ==== Results ====
  
-//(Add a list or attach slides detailing the achieved results here.)//+{{devsummit/201210/documentation/docwgeurobsdcon2012results.pdf?linkonly|Working Group Results Presentation}} 
 + 
 +---- 
 + 
 +{{tag>Historical}}
  
  • devsummit/201210/documentation.1345632140.txt.gz
  • Last modified: 2012/08/22 10:42
  • by GáborKövesdán