FAD Documentation Meeting 2009 06 14

From FedoraProject

2009-06-14 FAD - Documentation Meeting at Clemson

1 Meeting attendees
2 TOPIC - What went wrong? What went right?
- 2.1 What went wrong
- 2.2 What went right
  - 2.2.1 ==

Meeting attendees

Eric Christensen - Sparks Ian Weller - ianweller John McDonough - jjmcd Paul Frields - stickster Zach Oglesby - zoglesby Clint Savage - herlo David Nalley - ke4qqq Lee Brewer - uclugLee

TOPIC - What went wrong? What went right?

What went wrong

Changing Release Notes data 11111

* Two days before F11 was released, the release notes beats on wiki were still changing * Audio change * Networking issue * Expect full-timers to include info

Secret cabal-driven freezes that aren't communicated 1111111

* (leading to people not knowing about freezes occurring and when RN data needed.) * this is also a comms problem on our part.

Too many rogue documents. 1111
Getting RPMs pushed - going through f13 takes as much time as building the rpm 11111

* We need to be able to push packages ourselves (i.e. need instructions, guidelines, etc.) * Not enough packagers in Docs * Only f13 and stickster know how to push RNs -- need more co-maintainers

Could use more clarity understanding on what is implied by freezes, trans, etc 11
Need more interaction with L10n 11
Bugs not being filled out in timely manner 111

* Many RN bugs arrive at the last minute that were known early on -indeed (SEE ABOVE)

Need to centralize where bugs are filed (too many choices -- BZ, Trac instances...) 11111

* BZ even has too many subchoices (components, etc.)

Poor notations on where/how bugs/issues should be filed 1
Wiki search SUCKS BIG TIME!! 111
No good documentation on moving things from wiki to DocBook/Publican stores 11
Could use more consistency in wiki markup 1111
Need better documentation on what we want to use from DocBook markup 111
No good process for dealing with orphan documents 11
RN documents are not all in one place (about-fedora, readme's, etc.) 11
Lack of understanding of release schedule process 11
Publican and Fedora/GNOME lang codes not consistent 1

* Not at all clear how login lang selected is used

Translators having too much work. 1
Release notes are ill-defined 11111

* Too long for normal users to read * Beats have inconsistent levels of content * Need some separation

We don't know anything about visit statistics for docs.fp.o 111
We need a more rigorous freeze on wiki release note beats 11

 * Notes to f-docs-l, f-trans-l f-dev-l several times before each milestone

BZ URL ulink default in Publican is unhelpful at best 11111
Not clear if remaining (obsolete? unmaintained?) docs need conversion to Publican (strikes me as part of undefined orphan process) 1111
docs.fp.o site sucks (Mo knows) 11111

* Need solution for people to install a doc just for their lang, in their format * No CMS, no easy publishing, high barrier to participation * No real indexing...

What went right

DOCS PEOPLE ROCK
Many more docs/guides available than ever before!! (we rocked!)
The wiki didn't asplode, but should have. (yay!)
Everything seemed a lot more organized this release
+ Packaging is easier than it sounds
+ The install guide is awesome
++ Some folks really rolled up their sleeves and helped - zoglesby, laubersm, rudi
much better collaboration this release cycle
felt far less rushed than F10
stickster and quaid got out of the way and Sparks got run over
Brisbane folks represented, yo
Red Hat relicensed guide material in a way where we can generate community presence around them

TOPIC - F12 and Beyond

Voted for these goals in order of decreasing priority:

Better communication and interaction with other teams and program manager 1111111

* Docs Leader should attend/audit/log/read other project meetings * L10n * Design * Websites * Appoint liasions to other sub-projects rather than overloading DPL with meetings * Release schedule needs to include items for announcements to other teams * Docs Project sit down (virtually) with poelcat and grok the schedule and release process

docs.fp.o site sucks (Mo knows) 11111

* Zikula * Zikula IS *THE* SOLUTION. * Track record * Participation by their upstream in Fedora == BIG + * Package all the pieces. * Train the people * Migrate all the EOL guides/docs into it. * Tagging/categorization of documents by Lang, Release, Format (, subject matter?) * Eight modules remaining to be packaged (no review BZs yet) * Pervasive bundling of libraries * Need to package some PHP libraries to make this happen * SHA-256 library * Puppetization of configs has started, but is incomplete * Infrastructure is blocking on modules/packaging * Zikula will help with infrastructure testing/tuning

Need guide for wiki and DocBook markup 11111

* Clean up Help:Editing * Move many Docs wiki pages to Archive: and start over! * Create a getting "started guide" that tells you the what and how and provide links to short howtos * Two docs: * Quick Start Guide on the wiki * Documentation Guide in formal repo

Release Notes Issues

* We need a more rigorous freeze on wiki release note beats 11111 * RN documents are not all in one place (about-fedora, readme's, etc.) 1111 * Two documents... one for "normal users" and one for "advanced users". * Normal users = front-end features -- Created by Mktg & Docs * Links to the RN section (Advanced users) for those that want to know more. * Advanced users = back-end features + front-end features -- Created by Docs * Schedule * Marketing completion of talking points/tour * Tour should provide a link to upgrade page * Docs editing content * Has to be ported to the appropriate container (Zikula, website..., tupperware(TM), ziplock(R) bag?) * Screen shots have to be done * Translated

We don't know anything about visit statistics for docs.fp.o 1111
Release notes are ill-defined 1111
One target for bugs, consistent pointers across Publican, wiki, docs website, etc. 1111
Need to understand release schedule and what is implied by freezes, trans, etc 1111

* Note each line item/milestone on the wiki and explain what are the action items to complete it

Getting RPMs pushed - going through f13 takes as much time as building the rpm 111
Need to have process and deal with old/orphaned/rogue wiki documents 111

* (https://fedoraproject.org/wiki/User:Sparks/BZ_and_Guide_Table)

Improve understanding and communication with L10n 111
No good documentation on moving things from wiki to DocBook/Publican stores 11

TOPIC - A non-translator's introduction to the POT/PO model

Nearly every programming language has a gettext library
(opened up readme.pot in Gobby)
<![CDATA[blah]]> will make the string hidden from gettext in XML
msgid and msgstr
some tags are left in the msgid (such as <filename/>)
translated, untranslated, and fuzzy

* it uses an algorithm to decide on whether a new string is fuzzy or brand new

TOPIC - Packaging instruction

yum install fedora-packager

Zikula modules Content Version 3.0.3 - source tagged in SVN here: http://code.zikula.org/content/browser/tags/version-3.0.3 This is already being worked on by Lukas https://bugzilla.redhat.com/show_bug.cgi?id=492091

CoType - SUPERSEDED BY CONTENT, dawg Version 1.0.0 - download here: http://www.elfisk.dk/index.php?module=Folder&func=view&mode=folder.view&folderid=52 the source is probably in SVN somewhere, but not sure where.

crpTag - Everyone