'[kc-kde] how to write a summary'

[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kc-kde
Subject:    [kc-kde] how to write a summary
From:       "Aaron J. Seigo" <aseigo () olympusproject ! org>
Date:       2002-05-08 17:10:22
[Download RAW message or body]

Hello all...

i just realized i hadn't sent on instructions on how to write a summary. so 
here it is:

when choosing a thread to summarize, please be sure that it meets the 
following (loose and flexible) criterion:

 o the thread had reached some sort of summarizable conclusion before 
Thursday. things less than a few days old don't get covered in an issue since 
more discussion may occur making the summary innacurate.

 o the thread covers actual work/progress. we try not to cover vapour ware, 
arguments of wishlist items, etc...

 o the topic is interesting ;-)

once you have picked something to summarize, start a summary with the 
following:

<section
  title=""
  author=""
  email=""
  subject=""
  archive=""
  posts=""
  startdate=""
  enddate=""
>
<topic></topic>
</section>

title is what will appear as the title for the summar in the issue. author is 
you, and email is your email (these are both optional fields). subject is the 
subject line of the first email in the thread you are summarizing. archive is 
a link to the first email in the thread on lists.kde.org. posts is the number 
of posts in the thread. startdate and enddate are when the thread started and 
ended in the traditional email form, like: "Mar  1, 2002 03:17:53 -0700".

the <topic> tag allows you to define a general topic for that section. this 
used to be in the <section> tag itself, but was non-conformant XML so was 
recently moved to its own tag. you may have multiple topics, and assigning a 
topic is optional. it allows for grouping of summaries later on. try to keep 
the topics somewhat standardized so that similar summaries can grouped.

after any <topic> tags that you may supply, and before the closing </section> 
tag you put the actual summary.

the summary is done up in normal HTML with a few extra tags. the most 
important of which is the <quote> tag. when you go to quote from an email do 
so verbatim and w/out correcting spelling or grammar. you may truncate with 
[...] or rearrange whitespace if the original layout was unwieldy. with your 
quote in hand, you do something like this:

  <quote who="Aaron J. Seigo">This is what i said in my email</quote>

if a <quote> appears in a <p> it will be inlined in the paragraph. if, 
however, you do:

then it will appear in an indented block by itself.

please follow proper HTML with opening <p> and closing </p>s (not <br>s 
everywhere). replace "email style lists" with HTML lists. so that this:

 o item one
 o item 2
 o item 3

becomes:

 <ul>
	<li>item one</li>
	<li>item 2</li>
	<li>item 3</li>
 </ul>

similarly for numbered/lettered lists, use <ol>.

when you refer to a person for the first time in a summary use their full 
name. thereafter you can refer to them by their first name.

remember to hyperlink with <a> all ftp, email and web URLs.

try to keep the summary true to how the thread actual unfolded, but feel free 
to leave out redundant or unecessary comments. these are, after all, 
summaries =)  at the same time, try not to editorialize and provide your own 
personal opinions on things within the summaries. (there is an <editorialize> 
tag for just that, but we try not to use it...)

humour, levity and cleverness are all welcome, of course. this is supposed to 
be fun to both read and write.

thanks again for everyone who is looking to help out. are there any questions?

-- 
Aaron J. Seigo
_______________________________________________
kc-kde mailing list
kc-kde@mail.kde.org
http://mail.kde.org/mailman/listinfo/kc-kde
[prev in list] [next in list] [prev in thread] [next in thread] 