Need your help: Docs in the wiki

[Michael Schwendt]

On Sun, 08 Oct 2006 20:11:01 +0200, Thorsten Leemhuis wrote:

> > http://fedoraproject.org/wiki/Extras?action=recall&rev=113
> >
> > What did you dislike?
> 
> - [TOC] IMHO takes to much space in the most important area for a small gain

On the contrary, it adds readability when more sections and sub-sections
will be added to the page. While section headlines appear in the TOC,
individual bullets do not. What I didn't like about the previous page
layout was that there was not clear structure. A first attempt at creating
more small sections fixed that. The most recent page layout is a step
backwards, IMO. Now there is one huge section "Ressources for Fedora
Extras contributors" and everything squeezed into it: howtos, policies,
guidelines, hints, links to external urls,...

> - "Contributing to Fedora Extras" should be more on top --

... which is only a matter of moving it up or down. However, users
can also contribute to Fedora Extras, so maybe we should agree on
terminology first:

 - Users  [including pure consumers]
 - Contributors

Maybe decide between Contributors and Developers, but not use both?  Are
packagers "Package Developers", "Package Maintainers"? Do we need the
confusion? Are bug reports, patches, notifications or other things
submitted by Users not contributions, too?

Where cover anonymous CVS access? It may be relevant for Users, so
why not replicate it in the "For Users" section?

Then continue there:

 - Users  [including pure consumers]
   - general info about FE (including mentioning FESCo!)
   - documentation about the repositories and packages available
   - info about where to report bugs
   - info on resources like anon CVS

 - Contributors
   - howto on signing up and getting sponsored
   - docs on how to sponsor other contributors

 - FESCo

Then move on to technical stuff, policies, guidelines, hints:

 - Fedora Extras CVS services
   - howto, links to external CVS docs
   - admin requests  (could we use OTRS instead?)
 - Packaging
 - Fedora Extras build-system
   - plague howto, certs howto
   - needsign (build-results howto)
 - Repository status pages
   - FCXStatus pages  (could we use OTRS instead?)
   - Orphaned Packages
   - Retired Packages

> - "CVS Admin requests" should be in the same area as "Repository status
> pages for requesting manual copies and removals of packages"

Which is also only a matter of moving it. Somebody just needs to do it,
as it was in a different section for a long time.

There a mysterious  http://fedoraproject.org/wiki/Extras/Policy  page
in "Around Fedora Extras" which mentions policies not available on the
main page. All this is very difficult to navigate.

> - "How to sponsor a new contributor?" directly behind "How to get
> sponsored?" is IMHO confusing because one that interested in the later
> will never be intereted in the first

And now it is somewhere in the middle of a huge section, somewhere
under "Around Fedora Extras". IMO, everything about sponsorship ought
to be in the same section:

 - How to become a new contributor? -and- How to get sponsored?
 - How to sponsor a new contributor?

> - "Reporting Issues" -> was not sure about this one myself, but maybe is
> more a users task?

It is a bad link right now. Compare with the older
http://fedoraproject.org/wiki/Extras?action=recall&rev=113

> - "Contributing to Fedora Extras" and "Adding packages to Fedora Extras"
> -> Contributing to Fedora Extras means in 99% of the cases to add
> packages to Fedora Extras. So where is the difference?
> - Stuff that Packaging/ IMHO should have s separate section
> 
> Those are some reasons behind by re-organization.

Still not a reason to mix packaging topics with the entire rest which may
be relevant to existing contributors. While 99% of being a FE contributor
may be about dealing with packages, the Wiki page must cover many other
things: reviews, working in FE CVS, plague, sponsoring (unless it is moved
to a separate section). And it is only due to our focus on packaging that
a section "Contributing to Fedora Extras" does not include documents on
how to contribute other work (e.g. Security SIG, co-maintainership,
buildsys or QA related tools, ...)

In short, are you happy with the current look of the page?

To he honest, I was not happy with rev113, but found it to be a step
into the right direction.