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.
2009-04-19 17:00 UTC
#docs on irc.gnome.org
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.
Please do not edit this agenda unless you are Shaun. If you have suggestions for the agenda, place them in the Commends section below.
- Shaun will give a brief overview of Mallard and its status.
- Comments and questions will then be taken. Discussions may be cut short and sent to the mailing list.
- Discuss a multi-licensing scheme to be used on new documentation.
- Discuss what works and what doesn't with the status tracking proposal.
- Discuss people's experiences with Pulse, and how we can make it more useful.
- Missing Manuals
- What kind of documentation are we missing that could help the adoption of Gnome?
- Both user and developer documentation may be discussed.
- Think outside the text editor: How can we use other media to make more effective documentation?
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)
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!
Documentation Team Meeting 19 Apr 2009
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:
- Casual contributors can more easily just write a page without worrying too much up front about fitting it into a monolithic structure
- We can more easily track parts of documents and assign independent work to different writers
- 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.
- There are no plans to drop Docbook support for GNOME. Mallard and Docbook will both be maintained as there is no need to convert everything at once.
- Printing would be difficult within Mallard as Mallard is inherently non-linear.
- No current plans to integrate Docbook documents in to Mallard - for now, Mallard documents stay as Mallard, and Docbook stays as Docbook. Yelp will be able to read both, but inserting a final Docbook file into a Mallard document isn't planned.
As far as other projects adopting Mallard in the future, the spec needs to be finalized, and Shaun hopes to gives a presentation on Mallard at the first open source documentation conference in June in Candada. (http://www.writingopensource.com).
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.
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?
- Improved / updated GNOME User Guide, which needs a major overhaul
- Fedora doesn't even include the GNOME User Guide
- Ubuntu tried to integrate the User Guide in a general topic based structure, but it's tricky
- User Guide has always been put off being updated until Mallard is available
NetworkManager needs a good guide
- Improved Developer documentation
- Shaun has a goal to update the Platform Overview in the next year
- "Getting Involved with GNOME" guide
- "More guides, less manuals"
- Submit documentation bugs (or sections needing updates) from within Yelp
How do you help users who are brand new to using computers and lack basic skills? (Printed manuals, help with mice & keyboards, etc)
- Screencasts (How do you help with downstream adoption? Translations?)
- How could task automation enable encoding actions in a help manual? What kind of syntax (Linglish?) would be necessary?
- Yelp could use some speed optimizations, especially around search.
- Lack of contributors to Yelp
- Yelp's current search code is fairly basic, DonS has had previous dicussions with developers about Tracking / Beagle integration
- Main slowness is in the info files
- Challenges in using Beagle or Tracker include: Contributor to write the plugins; using rarian to find our documentation; encouraging downstream distros to standarize on Beagle or Tracker; localization