DocumentationTeamMeetingSummary6

Differences between revisions 12 and 13
Revision 12 as of 2005-07-01 07:42:51
Size: 9268
Editor: adsl-57
Comment:
Revision 13 as of 2005-07-01 07:43:33
Size: 9295
Editor: adsl-57
Comment:
Deletions are marked like this. Additions are marked like this.
Line 90: Line 90:


----
CategoryDocteam

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 suggested the creation of a "Wiki team" that is responsible for cleaning up the wiki as well as put order in the pages. Jeff Schering was open to the idea, but would like to have the DocumentationTeam wiki pages in order first before tackling the other wiki pages. Henrik commented that "cleaning the wiki is good but we should watch other people's toes," but the team can go out front with examples of good practice. Matthew identified the intial team members: himself, Phillip Cain and Daniel Robitaille. While the scope of work for the wiki team are not yet well defined, the group agreed that the wiki needs a lot of gardening work. Henrik also said that he's open on feature requests for structural wiki improvements.

jdub's suggestion on existing documentation already in the distro

jdub attended the meeting to discuss on working with existing documentation which will definitely make a huge impact in Ubuntu. He stated two areas with regards to working on Ubuntu documentation besides writing new books:

  • documentation already in the distro
  • working with upstream documentation (modifications)

The second point - working with upstream documentation is a medium-term goal that can be addressed further when soyuz/baz is workable.

The first point - documentation already in the distro is very much workable at the moment as the distro currently has an enormous amount of documentation available but not visible at all because it was not properly registered in the system (scrollkeeper,etc.) jdub shared a simple method in approaching this:

  1. finding existing documentation (we can start in /usr/share/doccd)
  2. documenting what we find (say, in a wiki page)
  3. ensure it's registered with existing systems (like scrollkeeper)
  4. start looking upstream to see if we can integrate better (by shipping docbook, translating source documentation formats, etc)

jdub also suggested that this undertaking should be done first in main so as not to overwhelm the whole project.

After this discussion, the group was very satisfied with the outcome of the meeting and adjourned. The next meeting was then scheduled on the 14th of July, 2005 at 22:00UTC.

Meeting Quotable Quotes

About the meeting in general...

{{{05:28 mdke this is the best meeting ever }}}

About moving on with the agenda...

{{{05:33 mdke let's move on or jsgotangco 's wife will kill him 05:33 squinn seconded}}}

About the upcoming docteam.ubuntu.com server

{{{05:26 jsgotangco ok let's pig out on PHP and JAVA on that server Big Grin :) 05:26 judax haha}}}

About jdub's upcoming email to the docteam...

{{{05:55 mdke its attaining mythical status now }}}

About the time of the meeting...

{{{06:14 jdub *cough* the time sucks! *cough* Wink ;-) [ignore me] }}}


CategoryDocteam

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