Packaging Guidelines Organization

[Karsten Wade]

On Tue, Dec 16, 2008 at 12:08:08PM -0800, Toshio Kuratomi wrote:
> Eric Christensen wrote:
> > Toshio,
> > So you basically need someone (or a group) to locate all the guidelines,
> > make sure they represent what needs to be accomplished for a package,
> > and then make a single page where all of the guidelines can be found
> > with ease?
> > 
> Maybe.  The end goal is that a reviewer or packager can easily find all
> the Guidelines that they need to make a quality package.  The
> organization comes in two parts:
> 
> 1) It's not obvious where all the Guidelines are and they might not be
> linked from obvious places.  I think the single page idea above could
> help with that.
> 
> 2) There's so many Guidelines and they won't all apply to every package.
>  That's where the decision tree type of solution comes in.  (Or a table
> of contents with "General Guidelines -- Check these for all packages"
> "Libraries -- Check these if your package has a library in any language"
> "Python -- Check these if the package is written in or interface with
> Python")

Table/matrix might be better.  A decision tree, especially implemented
in any hard markup (such as wiki or XML) becomes a maintenance hassle
each time a leaf node is tweaked.  Since we can anticipate the major
paths people want to take, we can probably group them together
relatively well.

If done on the wiki, this begs for a nice categorization, I think.
E.g. [[Category:Python packaging guidelines]] would be in each page
that had anything to do with Python packaging.  It could even be a
general page, so that general page appeared in *all* categories.  It
was for this kind of stuff that I think Ian looked to fedora-wiki as
the list for discussion.

However, Toshio, you skipped a third imperative:

3) Translate the guidelines.

It is the natural evolution of a document that when it is useful
enough to revitalize and care for over the long term, it is very
likely it needs to be available for translation.

We could leave this to the wiki l10n methods coming rather soon, but I
personally am quite skeptical about that.  Until it is proven and
used, it is not the normal pathway for getting content localized.

> Right now we have the Package Review Guidelines[1]_ sort of does #1 but
> it isn't complete.  The Review Guidelines and Guidelines[2]_ pages kinda
> reflect each other so they capture the main Guidelines.  But we still
> need to add other information such as the language specific Guidelines
> (examples: Python_ and Java_) and Scriptlets_ pages.
> 
> Working on only one of the two issues would be helpful but eventually we
> need something that addresses both problems.

Another imperative is enabling the FPC to work on the guidelines
easily.  We also want to organize the content collaboratively before
committing new structure to any other markup such as XML.  It seems
like a good idea to start reorganizing content in to categories.  We
can do this in a sandbox name space perhaps?

- Karsten
-- 
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20081216/2e729b7b/attachment.bin