how can I help?

Tue Jul 21 12:35:16 UTC 2009

On Mon, Jul 20, 2009 at 04:07:56PM -0700, Adam Williamson wrote:
> On Mon, 2009-07-20 at 15:28 -0400, Ricky Zhou wrote:
> > On 2009-07-20 12:02:16 PM, Adam Williamson wrote:
> > > I hate to be a stop-energy-spreader, but I'm not a big fan of the 'ten
> > > thousand tiny pages' school of documentation. It winds up with two major
> > > drawbacks: you can't ever find anything, and nothing gets updated.
> > > (Visit the Gentoo wiki to observe both in operation).
> > 
> > I think prioritizing documentation can help with this.  For example,
> > a list of wiki pages/things that absolutely most be updated every
> > release (does anything like this currently exist?)
> 
> I don't believe so. What I'd really like to see in this area would be
> the smart use of templates (this is something Wikipedia does to some
> extent); we could use these both to mark pages that will need regular
> attention, and to do some kinds of stuff automatically (for instance, if
> we had a {{version|current}} template - or something like that - it'd
> help immensely; there are many pages which just want to mention the
> number of the current release, for whatever reason. This may exist
> without me knowing about it, I don't discount the possibility :>)

We do already have this -- refer to the following pages:

https://fedoraproject.org/wiki/Template:FedoraVersion
https://fedoraproject.org/wiki/Template:FedoraVersionName
https://fedoraproject.org/wiki/Template:FedoraVersionNumber

I like the idea of the "Update these pages every release" page.  That
page should definitely then be linked on John Poelstra's release
schedule (maybe in Docs) as a task, i.e. "Update all pages listed on
the '<blahblahblah>' page," and a target date for that to happen,
probably the night before or day of release.

> > I hate to keep picking on these few points, and this is not meant to put
> > down our docs in any way, but I think the issue of
> > 
> > http://docs.fedoraproject.org/install-guide/f11/en-US/html/
> > 
> > vs.
> > 
> > http://en.opensuse.org/INSTALL_Local
> > http://en.opensuse.org/Installation/11.1_Live_CD
> > 
> > is a very serious one.

By the way, I think that adding a page like this to the wiki is very
easy.  However, if you actually read that page, you're going to find
that it's utterly useless at providing any information or answering
any questions about what's going on, beyond "What does this screen
mean?".  It's a nice tour of the screenshots that works only for
someone who just clicks next, next, next -- nothing more.  I'm not
saying we shouldn't have something like that, just that this
particular document has a very different purpose than the Installation
Guide, which actually tells you (if you read it) important information
about how to set up your installation.

> > Where will the (currently nonexistent) docs about how to properly setup
> > Apache go, for example?  I don't think we can get much worse than the
> > kind of outdatedness that you get with:
> 
> These are both good examples; if that's the kind of thing you're talking
> about I can't give a better idea than a Wiki / knowledge base article,
> from a documentation perspective. There's an argument that this
> information should be in the application documentation and if the
> instructions for Fedora differ significantly from what the upstream
> instructions are / should be, that's a bug...but that's a tricky area.

Since the upstream instructions almost always include "download from
here, then compile from source," I think the trickiness is
unavoidable! :-)  

> > Here's an example that happens to be commonly used in #fedora -
> > currently the first search result for fedora sudo, I'm happy to say.
> > 
> > http://fedorasolved.org/post-install-solutions/sudo
> > 
> > This is the kind of documentation that I think we need for many common
> > tasks.
> 
> Yeah, that's another good example. When I saw the word 'issues' I was
> kind of keying on 'bugs'. I don't think a Wiki page for every little
> task like this is a really awesome way to do things, but equally I've
> never been able to come up with a better one :\
> 
> > Perhaps if each of our HOWTO pages had a header listing the applicable
> > Fedora releases and date when the HOWTO was last updated?  I think that
> > something would be better than the nothing that we have now.
> 
> A header's OK, but you can't get to that information very easily. I'm
> sure we could think of something better, so we could have a way to know
> very easily when a page might be out of date...

Mediawiki does tell you the last time a page was updated in the footer
of every page it displays.  If you need it someplace in the content,
you can use the info at http://meta.wikimedia.org/wiki/Help:Variable
to do so.

{{REVISIONTIMESTAMP}}                                  <-- a bit harder to read
{{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}}    <-- easier to read

Categories are probably the best way to do this.  If it were me, I'd
probably consider categorizing pages in the releases to which they
apply, which makes things simple.  So for example, a category on how
to set up sudo would include:

[[Category:Howto]] [[Category:F9]] [[Category:F10]] [[Category:F11]]

-- 
Paul W. Frields                                http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://redhat.com/   -  -  -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug