FAD Documentation Meeting 2009 06 14

From FedoraProject

Jump to: navigation, search

2009-06-14 FAD - Documentation Meeting at Clemson

Contents

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

  1. 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

      • DONE! ***

I'd take the head: http://code.zikula.org/crptag/browser/trunk, but just in case it is non functional perhaps we could package 0.1.3 too? http://code.zikula.org/crptag/browser/tags/crpTag_0.1.3

MediaAttach - BZ SVN Head: http://code.zikula.org/mediaattach/browser/trunk/MediaAttach

mediashare - Paul SVN Head: http://code.zikula.org/mediashare/browser/trunk INCLUDES: phpPicasa - http://www.cameronhinkle.com/ V3.3 http://cameronhinkle.com/downloads/LightweightPicasaAPIv3.zip


menutree - Lee-nener nener Version 2.0.1: http://code.zikula.org/bianor/browser/tags/menutree/2.0.1

MultiHook - BZ SVN Head: http://code.zikula.org/multihook/browser/trunk/MultiHook

scribite - BZ Version 3.1: http://code.zikula.org/scribite/browser/tags/scribite/3.1

Custom Modules (no public source (yet))

==

FASAuth FedoraDocs Static_Docs

Custom Theme (no public source)

TOPIC - Perhaps an introduction to DocBook if there is interest