DocumentationTeamMeetingSummary6

Differences between revisions 3 and 9 (spanning 6 versions)
Revision 3 as of 2005-07-01 01:32:05
Size: 1522
Editor: adsl-57
Comment:
Revision 9 as of 2005-07-01 06:39:32
Size: 6429
Editor: adsl-57
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
=== Minutes of the 1st regular Ubuntu Documentation Project (UDP) Team meeting, June 30, 2005 === == Minutes of the 1st regular Ubuntu Documentation Project (UDP) meeting, June 30, 2005 ==
Line 5: Line 5:
=== Meeting participants === == Meeting participants ==
Line 18: Line 18:
=== Meeting minutes per agenda === == Meeting minutes per agenda ==
Line 22: Line 22:
 * '''Completion of the StyleGuide''' === Completion of the StyleGuide ===
Line 24: Line 24:
The UDP StyleGuide is currently being written by jeffsch, but he prefers to have members of the team to contribute to some sections of the book, since the team will adhere to it in writing current and future Ubuntu documentation. Sean Wheller has agreed to handle the Docbook section of the StyleGuide, while Jerome Gotangco will look into the section that involves writing for an international audience. Other team members who volunteered for the StyleGuide effort are Matt Galvin and Sean Quinn but did not specify on the sections they will work on but promised to look into the document. Matthew East indicated that while he cannot work on the StyelGuide, he will review all current documents in svn in reference to the StyleGuide once it is completed. There is an open issue on the section for Grammar, Punctuation, and Spelling. The UDP StyleGuide is currently being written by Jeff Schering, but he prefers to have members of the team to contribute to some sections of the book, since the team will adhere to it in writing current and future Ubuntu documentation. Sean Wheller has agreed to handle the Docbook section of the StyleGuide, while Jerome Gotangco will look into the section that involves writing for an international audience. Other team members who volunteered for the StyleGuide effort are Matt Galvin and Sean Quinn but did not specify on the sections they will work on but promised to look into it. Matthew East indicated that while he cannot work on the StyleGuide, he will review all current documents in svn in reference to the StyleGuide once it is completed.

As for the section on Grammar, Spelling and Punctuation, there were no volunteers at the moment, but people are free to write to whatever style at the moment and leave the editorial work and set a review period for all books. There was also a suggestion to adopt the [http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html Chicago Manual of Style] but since only a selected few of the team are familiar and have access to the said document (it is a bit pricey), there is no point of specifying it, although it can be used to resolve writing style disputes.

=== Doc Planning - creating document plan pages for our books ===

Jeff Schering suggested that all books under DocteamProjects should have a document outline/specification similar to what is written in the StyleGuide wiki page. He mentioned that ''"we need to know who we are writing for, and the purpose of the doc(ument)."'' Matthew East added that a page like this can greatly help newcomers who would like to contribute to the project. Sean Wheller reminded the group that this is already available in the current svn, and that it was an idea that never took off. He also added that he will be creating a docspec directory for kde in svn, although the general consensus of the group is to create the plan pages in the method they prefer, be it wiki or in svn, with the minimum being something similar to what the StyleGuide has. Therefore, all people involved in their projects should make a document plan page and have it visible in the wiki.

=== Document Format to be shipped ===

Sean Wheller has proposed to use HTML in shipped documents to enable certain features and functions that was not possible with shipping XML. The biggest advantage into going the HTML route is both shipped document and online reference are one and the same, with no deviation at all. The HTML can also be shown correctly in Yelp with some custom CSS code and even utilize Yelp's side bar system. Henrik Omma also agreed on the HTML route and said, ''"I'd like to see HTML for both GNOME and KDE."'' Matthew East asked if there would be any problems that the team would likely have with the developers on the HTML issue. Since there was no developer present during the meeting Henrik suggested that they catch up with Matt Zimmerman during the Edubuntu summit and get clarity on the process. Sean Wheller added that this is a "tradeoff decision," as to some documents included in the distro such as ''update-manager'' and ''hwdb'' must conform to Gnome. The team is solid on the HTML route but will need to resolve the matter to the [http://www.ubuntulinux.org/community/processes/techboard Technical Board] soon.

=== Document Profiling ===

Seah Wheller again pointed out that there wouldn't be any problem with Document Profiling if we use HTML, since the profiling method is essentially a time saver, enabling the team to develope two or more books in a single XML instance. A good example of a current project being profiled is the Installation Guide. Matthew East said that he didn't have a problem with the concept of profiling, but is more concered in the possibility of making the source document too complex. Jeff Schering asked on how to decide on what gets profiled and the criteria. Jerome Gotangco noticed that profiling can only happen in specific documents like an install guide. Sean Wheller confirmed that it is a selective application and not recommended for all books. Henrik was concered that profiling may tempt the team from writing things too general in a form when there really are differences between documents. Jeff Schering suggested that currently profiled documents in svn stay as profiled while the other documents remain as-is, especially if its not a candidate for profiling. Matt Galvin mentioned that he has started working on the faqguide and learning that writing and using profiles wasn't that much of a problem for him. Sean Wheller added that at least 4 people doing svn work has done profiling and not much of a problem. Matthew East suggested that a simple profiling explanation on the wiki can help. While the issue on profiling is still not closed, the team has recognized the potential of using this method and will be discussed again in the list.


=== Draft documents at docteam.ubuntu.com ===

Henrik announced that he got to talk to elmo about this and we're definitely getting it, most likely as a linode server. This will probably be available anytime this July as they are negotiating a bulk deal on the service not just for the docteam but for other Ubuntu teams as well. As for help.ubuntu.com, this will stay on the Ubuntu servers, since these documents are already frozen. The docteam.ubuntu.com server will be used as a staging area for status reports, document previews, etc. On the issue of svn, we will stay with the current svn and discuss further the plan on Baz/Baz-NG migration, which will be tackled in another meeting.

=== UDP Wiki team ===

Matthew East

Minutes of the 1st regular Ubuntu Documentation Project (UDP) meeting, June 30, 2005

IRC log of the meeting is available: http://people.ubuntu.com/~fabbione/irclogs/ubuntu-meeting-2005-06-30.html

Meeting participants

IRC Nick

Full Name

jsgotangco

Jerome Gotangco

froud

Sean Wheller

mdke

Matthew East

mgalvin

Matt Galvin

hno73

Henrik Nilsen Omma

squinn

Sean Quinn

jeffsch

Jeff Schering

judax

Troy Williams

jdub

Jeff Waugh

Meeting minutes per agenda

Note: Current status of UDP projects can be found in the DocteamProjects page

Completion of the StyleGuide

The UDP StyleGuide is currently being written by Jeff Schering, but he prefers to have members of the team to contribute to some sections of the book, since the team will adhere to it in writing current and future Ubuntu documentation. Sean Wheller has agreed to handle the Docbook section of the StyleGuide, while Jerome Gotangco will look into the section that involves writing for an international audience. Other team members who volunteered for the StyleGuide effort are Matt Galvin and Sean Quinn but did not specify on the sections they will work on but promised to look into it. Matthew East indicated that while he cannot work on the StyleGuide, he will review all current documents in svn in reference to the StyleGuide once it is completed.

As for the section on Grammar, Spelling and Punctuation, there were no volunteers at the moment, but people are free to write to whatever style at the moment and leave the editorial work and set a review period for all books. There was also a suggestion to adopt the [http://www.press.uchicago.edu/Misc/Chicago/cmosfaq/cmosfaq.html Chicago Manual of Style] but since only a selected few of the team are familiar and have access to the said document (it is a bit pricey), there is no point of specifying it, although it can be used to resolve writing style disputes.

Doc Planning - creating document plan pages for our books

Jeff Schering suggested that all books under DocteamProjects should have a document outline/specification similar to what is written in the StyleGuide wiki page. He mentioned that "we need to know who we are writing for, and the purpose of the doc(ument)." Matthew East added that a page like this can greatly help newcomers who would like to contribute to the project. Sean Wheller reminded the group that this is already available in the current svn, and that it was an idea that never took off. He also added that he will be creating a docspec directory for kde in svn, although the general consensus of the group is to create the plan pages in the method they prefer, be it wiki or in svn, with the minimum being something similar to what the StyleGuide has. Therefore, all people involved in their projects should make a document plan page and have it visible in the wiki.

Document Format to be shipped

Sean Wheller has proposed to use HTML in shipped documents to enable certain features and functions that was not possible with shipping XML. The biggest advantage into going the HTML route is both shipped document and online reference are one and the same, with no deviation at all. The HTML can also be shown correctly in Yelp with some custom CSS code and even utilize Yelp's side bar system. Henrik Omma also agreed on the HTML route and said, "I'd like to see HTML for both GNOME and KDE." Matthew East asked if there would be any problems that the team would likely have with the developers on the HTML issue. Since there was no developer present during the meeting Henrik suggested that they catch up with Matt Zimmerman during the Edubuntu summit and get clarity on the process. Sean Wheller added that this is a "tradeoff decision," as to some documents included in the distro such as update-manager and hwdb must conform to Gnome. The team is solid on the HTML route but will need to resolve the matter to the [http://www.ubuntulinux.org/community/processes/techboard Technical Board] soon.

Document Profiling

Seah Wheller again pointed out that there wouldn't be any problem with Document Profiling if we use HTML, since the profiling method is essentially a time saver, enabling the team to develope two or more books in a single XML instance. A good example of a current project being profiled is the Installation Guide. Matthew East said that he didn't have a problem with the concept of profiling, but is more concered in the possibility of making the source document too complex. Jeff Schering asked on how to decide on what gets profiled and the criteria. Jerome Gotangco noticed that profiling can only happen in specific documents like an install guide. Sean Wheller confirmed that it is a selective application and not recommended for all books. Henrik was concered that profiling may tempt the team from writing things too general in a form when there really are differences between documents. Jeff Schering suggested that currently profiled documents in svn stay as profiled while the other documents remain as-is, especially if its not a candidate for profiling. Matt Galvin mentioned that he has started working on the faqguide and learning that writing and using profiles wasn't that much of a problem for him. Sean Wheller added that at least 4 people doing svn work has done profiling and not much of a problem. Matthew East suggested that a simple profiling explanation on the wiki can help. While the issue on profiling is still not closed, the team has recognized the potential of using this method and will be discussed again in the list.

Draft documents at docteam.ubuntu.com

Henrik announced that he got to talk to elmo about this and we're definitely getting it, most likely as a linode server. This will probably be available anytime this July as they are negotiating a bulk deal on the service not just for the docteam but for other Ubuntu teams as well. As for help.ubuntu.com, this will stay on the Ubuntu servers, since these documents are already frozen. The docteam.ubuntu.com server will be used as a staging area for status reports, document previews, etc. On the issue of svn, we will stay with the current svn and discuss further the plan on Baz/Baz-NG migration, which will be tackled in another meeting.

UDP Wiki team

Matthew East

DocumentationTeamMeetingSummary6 (last edited 2008-08-06 17:00:45 by localhost)