This site has been retired. For up to date information, see handbook.gnome.org or gitlab.gnome.org.


[Home] [TitleIndex] [WordIndex

Documentation Team Meeting for 2009-04-19

We will be holding a documentation team meeting on April 19, 2009 to discuss the progress of Mallard and the future of Gnome documentation. Please plan to attend.

When

2009-04-19 17:00 UTC

Where

#docs on irc.gnome.org

Coordinator

Paul Cutler (pcutler)

The meeting is planned to last roughly one hour. We will discuss the points on the agenda below. Paul will keep the meeting moving and take minutes. It is important that the meeting does not devolve into general conversation, so please respect Paul's role as coordinator. After the meeting, the minutes will be posted to this page and announced on gnome-doc-list. If there are outstanding discussions, we may continue them on the mailing list.

Agenda

Please do not edit this agenda unless you are Shaun. If you have suggestions for the agenda, place them in the Commends section below.

Comments

ShaunMcCance: Add comments or suggestions for the agenda here. Please prefix your comment with your name.

MatteoSettenvini: can someone link to a document with the status tracking proposal? I'd like to put in agenda also a point about the possibility of making Yelp a tool to directly edit documentation, like Monodoc does. Even if we don't "wikify" the pages (which would be better, imho), the ease of use could help new people contributing.

PaulCutler: @Matteo: Read the ProjectMallard link above, it has a link to FoieGras which is the editor, which is similar to what you propose. Pulse (http://www.gnome.org/~shaunm/pulse/web/) is the doc status tracker that Shaun is working.

GianMarioTagliaretti: What can we do to integrate python docs with the infrastructure? At present I've been working writing tons of XML files, see for example the docs I'm writing for gio python bindings but also pygtk, pygoocanvas, (add almost any py* here)

LouisHandfield: I wrote down some (mostly repetitive) ideas at DocIdeas, parts of which could probably be integrated to FoieGras.

MiloCasagrande: I added some thoughts, ideas and started a kind-of-comparison with help systems of other operating systems in a subpage of my personal page: Thoughts. It's not tight related to the IRC meeting, but to documentation in general. Is work-in-progress, and probably will always be!

Minutes

Documentation Team Meeting 19 Apr 2009

Agenda: http://live.gnome.org/DocumentationProject/Meeting20090419

Mallard

ShaunMcCance, GNOME Documentation lead, gave an overview of Mallard.

Mallard is a documentation format that has been in the works for a couple of years, that will make it easier for documentation writers through:

  1. Casual contributors can more easily just write a page without worrying too much up front about fitting it into a monolithic structure
  2. We can more easily track parts of documents and assign independent work to different writers
  3. Dropping in extra information is super-easy and doesn't involve editing other files, which means distros can extend our documentation to suit their needs

The Mallard spec is available at http://www.gnome.org/~shaunm/mallard/. It is a priority for Shaun to have a draft spec complete by the end of April. Once this is complete, contributors should be able to write a Mallard document and convert it to html to post on the web, or convert to other formats. The major task after that is make it work with Yelp, and Shaun will need DonS' help. Shaun's goal is to have Mallard working with Yelp by the end of May.

Mallard Q&A:

Licenses

Due to concerns in the community around the GFDL, Shaun has been looking into selecting a new license. With the work that needs to be done to GNOME documentation for GNOME 3.0, we have a unique opportunity to choose a new license. Shaun has been discussing license choices with Luis Villa of the GNOME Foundation Board, and the Creative Commons Sharealike 3.0 license appears to be a viable option. (CC SA 2.5 was considered to be non-free by Debian, but 3.0 fixes that). Another options is to dual license GNOME Documentation CC SA 3.0 and GFDL which has an advantage of giving more options to downstream distributors, but limits the GNOME Documentation team with where they can pull content from. If you only use a single license, you can't pull content from documents using the other license. (Wikipedia is moving towards a similar dual license strategy).

It is being recommended that code samples within documentation use a more permissive license, such as the CC0 license which can be reviewed at http://wiki.creativecommons.org/CC0.

One idea brought up by tchernobog is include a license attribute for the code elements in documentation as well. Longer term Shaun is also thinking about how this affects developer documentation in addition to user documentation.

Status Tracking (http://live.gnome.org/DocumentationProject/StatusTracking)

Pulse (http://www.gnome.org/~shaunm/pulse/web/) is a web application Shaun has developed to assist in tracking a document's status. The lgo page StatusTracking shows a proposed workflow for recording status information in documentation. Pulse should assist in helping authors remember to use status tags when updating documentation. Mallard will be able track status per page. It is Shaun's hope to deploy Pulse later this summer upon completion of the Mallard spec.

Documentation team members are encouraged to think about and discuss how the proposed workflow maps to their writing model, and how to encourage adoption of status tracking in GNOME documentation.

Missing Manuals

This discussion was open ended focusing on what can the GNOME Documentation Team do to create better documentation, including, but not limited to, manuals. What tools would help GNOME users to learn?

Open Q&A


2024-10-23 11:04