Ubuntu Documentation Team Roundtable

Link to the pad:http://pad.ubuntu.com/uds-1311-community-1311-docteam-roundtable

Doug Smythies notes for the UDS (2103.11.02):

Inter-group collaboration / cooperation:

Translations:
Objective – improve the relationship, and take into consideration that translations tend to occur not by deadline, but by whenever.
Note: In general e-mails to <email address hidden> go unanswered.

The master translator roll up task list uses the DeskTop help docs "package" as its reference. It should use the DeskTop help "project". Each cycle, this causes confusion. The proper solution would be to fix it, but a possible workaround solution would be to modify our workflow and do a full "package" update from the "project" at documentation string freeze.

The master translator roll up task list does not include the serverguide. Why Not?

Core developers (?):
The final default desktop background is typically only set extremely late in the release cycle. There is no reason it can not be set at the very beginning of the cycle. Then new documentation screenshots could be done in less of a panic. (for 13.10 they were not re-done when the default background changed).

Unknown:
For the DeskTop help documentation, there is a jpeg file that includes the entity of the release name. This file has not been updated since Quantal, because nobody in the doc team knows the procedure. Where does the file come from? Who supplies it? Do we have the rights to publish it? This should occur at the very beginning of the cycle. So, specifically for Trusty Tahr, where is the chosen 250 pixels wide by 200 pixels high picture of a Tahr?

Upstream issues:
During the 13.10 cycle, the docs (both the serverguide and Ubuntu DeskTop help) uncovered a number of issues where the root causes are really upstream GNOME yelp issues. In some cases a workaround was devised, some cases are not that important (other than to Doug S., who is a fanatic about these things), but one seemed to cause some cascading issues with the translators. These should be addressed as early in this cycle as possible, towards including any yelp upgrades early enough for people to use for further docs improvements and checking.
Work Item: [T.B.D.] try to entice Shaun McCance, or some other GNOME resource, into helping us, or at least get their opinion on the related upstream bug(s).
Or toss out the conditionals.

Serverguide:
The serveguide suffers from lack of subject matter experts input. In a volunteer driven system it is not clear how to force the issue. In a for profit company, developers would have to supply thorough documentation, it wouldn't be an option. Just stating the issue is all, I do not have a proposed solution.
There are still issues with PDF compile for many of the other languages as a result, only English PDF was published on help.ubuntu.com for 13.10, whereas the goal had been to publish all languages in both HTML (done) and PDF (not done).
Work Item: [dsmythies] dig into bug 922251 and any other issues with the Serverguide PDF compile for other languages.

DeskTop Help docs:
Agenda item: How we can improve the "getting started contributing" process?
There is little value in spending tremendous amounts of time on this, as was done in the 13.10 cycle, if potential doc contributors aren't going to use it as a reference towards executing and submitting work via merge proposals.

Documentation committer specific wiki pages:
Serverguide is in good shape.
DeskTop help docs: Needs a lot of work (or to even be created, if the generic one is not used). Should be a priority for this cycle.

Comment from Little Girl with my apologies if this is in the wrong place - feel free to delete or move it (2013-11-03):

I had a chat with Shaun in IRC about broken conditionals in the ubuntu-docs repository (see http://irclogs.ubuntu.com/2013/11/02/%23ubuntu-doc.html for the log). It seems the conditionals inside of <info> elements will not work no matter how you write them, and there's no current work-around for them. Shaun mentioned that a new version of conditionals can happen, so that's something to possibly look forward to. Meanwhile, a decision is needed on how to handle broken conditionals. For now, the best solution is probably to rewrite any broken conditionals as content that either includes all conditions or is generalized and doesn't make a reference to specific conditions.

Validation of the .page files is currently done with the ubuntu-docs/ubuntu-help/C/check_validation.sh script, which uses an xmllint command to check the files. This command can't find broken conditionals, so Shaun recommends adding the version="1.0 if/1.0 ui/1.0" attribute to the <page> elements. This will make it possible to use the yelp-check validate *.page command or the yelp-check validate --strict *.page command to check for broken conditionals.

The yelp-check utility is part of the yelp-tools package, which is only installed by default in Ubuntu GNOME. All other Ubuntu derivatives can find it in the package manager. I've installed it and tried it, and from my brief experimentation with it so far, I recommend adding the version attributes to the .page files gradually. Many of the ubuntu-docs .page files fail to validate with yelp-check and will need to be fixed, which will probably be a slow process.

Work items:
[nskaggs] Review DocumentationTeam wiki and give feedback to simplify for new contributors: DONE
[knome] Review the https://help.ubuntu.com/community frontpage and try to make it look better/clearer: DONE
[lyz] Put a call out to the list to get reviewers for DesktopGuide: DONE
[bregma] circulate updates to ubuntu-doc when major features land/change: TODO
[lyz] Schedule next IRC meeting: DONE
[lyz] Work with IS to rename help wiki landing page: DONE