Meeting minutes - today's Env-and-Stacks WG meeting (2013-11-19)

[Stanislav Ochotnicky]

Quoting Toshio Kuratomi (2013-11-25 18:43:23)
> On Mon, Nov 25, 2013 at 04:19:03PM +0100, Petr Kovar wrote:
> > Hi all,
> > 
> > I would like to see these best practices covered in our Fedora formal
> > documentation, hosted on docs.fedoraproject.org. Currently, there are
> > different HOWTOs and guides on the Fedora wiki, some of them are outdated,
> > some are not, so instead having a single guide that would merge content from
> > those wiki documents is something I would like to focus on.
> > 
> I'm not certain if this would work well.  I do agree that the various
> places that you can find the documentation is confusing.  However, I think
> that putting something under docs.fp.o will just lead to:
> http://xkcd.com/927/
> 
> Right now we have a standard location for official Packaging Guidelines...
> the Packaging: namespace on the wiki.  These other sources of information on
> the wiki have grown up because packagers want to have something that they
> can modify very quickly and easily.  docs.fp.o will be less quick to modify
> than documents in the Packaging: namespace so I fear we wouldn't be able to
> replace the proliferation of individual wiki documents and just end up
> adding another location where people could look for information that may or
> may not be up-to-date and may or may not conflict with the currently
> approved Guidelines.

So perhaps there are multiple issues. I guess we can agree that most guidelines
are currently too chatty, full of irrelevant examples and cross-linking and not
enough clear rules. 

I'd suggest three goals:
    1. Create a simple list of principles which will guide rest of guidelines
        - no bundling, consistency, verifiability, etc
        - All guideline MUSTs should go back to one of these principles
    2. Simplify current guidelines to MUSTs, get consistent "look & feel", most
       likely with help from docs team. Currently each guideline has a different
       style
    3. Create, curate and allow maintainers to have a common space for "best
       practices". 

The last part would help with a lot of different locations and personal
namespaces that get old and nobody sees them. In the common space we could
curate and possibly vote out outdated documents. 

We are working on similar simplification in Java guidelines:
current guideline: https://fedoraproject.org/wiki/Packaging:Java
draft: https://fedoraproject.org/wiki/User:Akurtakov/JavaPackagingDraftUpdate

additional howto: https://fedorahosted.org/released/javapackages/doc/

Above means we can maintain howto together with the code which it covers
(macros, helper tools, man pages). Similar approach could be encouraged (in case
there was agreements this is the preferred way)

-- 
Stanislav Ochotnicky <sochotnicky at redhat.com>
Software Engineer - Developer Experience

PGP: 7B087241
Red Hat Inc.                               http://cz.redhat.com