docs ideas, dream big
Peter Boy
pboy at barkhof.uni-bremen.de
Mon Aug 22 13:33:00 UTC 2005
Hi,
sorry, the following is much too long. If you don't like long texts
here, please skip.
Am Donnerstag, den 18.08.2005, 12:58 -0700 schrieb Karsten Wade:
> One thing we lack is a list of what to write for new authors. I'd like
> to fix that.
Full ack!
As I mentioned in the weekend's thread "Why you are lurking", I suppose
it would be helpful to provide some decent structure for orientation in
the documentation process, that is, to develop some sort of long term
goals what parts should make up the Fedora Documentation if it would be
ready. One way to do it is to conceptualize an open but systematic
framework of topics (a kind of table of contents for a series of
publications).
Currently the pieces of documentation make a somehow eclectic and
unstructured impression (from the perspective of a naive end user, who
doesn't know about all the details and difficulties, without wanting to
hurt anybody of the participants here!). It makes at the first moment an
impression of rather a collection by chance as a (at least potential)
systematic source of orientation.
On one hand this makes it hard for the end user to find relevant
information and to put a value on it, on the other hand it is a steep
curve for a potential contributor. He/she has to develop a complete idea
about what to contribute and has no idea at the beginning weather it is
worth to consider a contribution because there is no hint, weather it
may fit into the picture.
Just another problem is, that end user documentation and internal
project documentation are mixed on the pages (perhaps with a slight
domination of the internal documentation, which is good for the project,
but may be confusing for the uninitiated).
The current state and working strategy is, I suppose, a very efficient
way to start a project and to produce some results and output quite
quickly (in order to have something on stage). I suppose the project has
reached a stage where some meta planning might be possible and helpful.
Just another point: If you know what are you looking for, you can
actively try to find authors by suggesting specific themes. Or you may
look for existing documentation (there is a lot of it existing around)
and ask their authors to contribute it to the FDP.
Just another idea: The project may consider to adopt the very efficient
idea of release note beats to the documentation itself. There could be 2
or 3 different types of contributions: guide/tutorial as known yet, the
FAQ type and something like a "technical note", very short and for a
limited scope, but which is seen as usefull in the context of the whole
documentation.
OK, to critize a work is quite easy and doesn't necessarly contribute to
progress. To produce something by oneself which can be critized by
others is another party. I've gathered the existing pieces of
documentation, mixed it with a little bit of phantasy and came up with a
framework, which might serve as a very rough initial proposal for such a
long term goal and may work as a way to structure the wiki pages, too.
The + denotes a broader section, - a singe tutorial/guide, # additional
comments.
I hope it gives some perceivable structure what is needed and is is open
enough for every idea somebody may contribute.
End User Documentation
----------------------
+ Short Overview over the documentation (one page)
# Information what is the goal
# Information about the current status
# Information what pieces can be found
# and why they can be found
+ Release Notes
# (published)
# new development for FC5
+ Installation Guide
# (published)
+ Start Using Fedora
- Stuarts text nextsteps
# needs perhaps some minor rework
- Finding help
# where to find documentation
# man pages / info system
# gnome help system quite special
# links to general informations
(LDP project, Howto's, ...)
# generate a quick link an desktop or panel
- where to find software
# Fedora tracker
# Fedora extras
# third party repositories
# some caveats (interoperability)
- Guide up2date
# finished but deprecated
- Guide yum for update / install
# published
- How to handle and reporting bugs
# (some material existing)
- Fedora Guide to Useful Linux Documentation
# (new)
- Command line survival guide
# ( new )
+ Using Fedora as a Desktop System
- Guide to Open Office in Fedora
# special configuration by Fedora
# access evolution address book
# file dialogs
- Guide to Firefox
# Fedoras preconfiguration
# how to customize
# where are the data stored
# managing downloads
# managing plugins
# how to handle third party plugins
- Customizing the Fedora Desktop
# launching often used programs
# starters on the desktop
# rearranging menues
# customizing nautilus (broser mode)
# Adding stuff to the panel
# differences / enhancments to standard Gnome
desktop
- Keeping up2date
# (finished CVS)
- Hotplug Tutorial
# (finished / CVS)
- Managing / Using wireless cards
# howto compile drivers not included in fedora
# list of available drivers
+ Using Server procecess
# each guide should concentrate on the Fedora specific
# preconfiguration, Fedora delivered tools, hints how
# to translate the server specific general documentation
# into Fedora specific variants, links to further readings
- Guide to using and configuring HTTP / TOMCAT
# published as HTTP / SELinux
- Guide using / configuring postgres
- Guide using / configuring mysql
- Guide using / configuring samba
- Guide using / configuring Internet Gateway
- Guide using / configuring Proxy Server
# finished / CVS
- Guide using / configuring Mail Server
# sendmail as preconfigured standard
# postfix as an alternative
- Guide to managing services
# start during boot
# how to add services (compiled from tar balls)
- Alternatives
- Installing / configurint Exim
+ Coping with recent technologies in Fedora / technology changes
- Guide udev
# (published)
- Guide SELinux
# (published as FAQ)
- Guide using zen
- Guide Using Java
+ Developing with / for Fedora
- General Developer Guide
# published, but unfortunately not
part of the FDP?
- Packagers Handbook
# by Extra Project
# perhaps some information independent of
extras usefule ("home made / users internal packages")
- Guide using / configuring Eclipse
- Developing with python
# importance: Fedoras way for scripts an system management
- Alternatives / Extras
- Guide using / configuring netbeans
+ Administrators Guide to Fedora (Hell)
# may be to be diffentiated in daily admin (casual user)
and special admin tasks (experienced admins)
- overall guide to Fedora's internal infrastructure
# etc/sysconfig, what is where and why
- Kernel Compilation Tutorial
# (something existing)
- sudo guide
# (finished / CVS)
- Securing file systems
# (existing / CVS)
- System Hardening
# (existing / CVS)
- Samba Ldap Tutorial
# (CVS)
- Clan Antivirus Tutorial
# (existing )
- Managing Menues
# perhaps not necessagy with FC5 menue editor?
# manage different menues for different users
# how menu system works
- how to add printers
+ Special purpose configurations
- Stateless Linux
# (published)
- pxe boot environement
# using pxe to manage windows desktops
- setting up a mirror
# in CVS
- Installing a Simple Gateway Server
# (existing?)
- Using Fedora as a home network Server
# putting various pieces of other
documentation parts to a specific
purpose
- Using Fedora as a small business workgroup Server
# putting various pieces of other
documentation parts to a specific
purpose
# warning: do not use it for enterprise level
situation
+ Useful misc Information
- Jargon Buster
# (published)
Fedora Documentation Project internal Documentation
------------------------------------------
(preferrable apart from the End User documentation as a separate page)
+ FDP Quick Start Guide (deprecated)
+ FDP Documentation Guide
# published
+ Release Notes Beat Writer
# (something existing)
+ FDP Example Tutorial
# (finished / CVS)
+ DocBook / Emacs Quickstart
# (finished / CVS)
+ FDP Style Guide
# (finshed / CVS)
+ Translation Guide
# May be unrelated to the FDP, or may be
useful for the FDP, too?
Thanks for your patience to read up to this point.
Peter
More information about the docs
mailing list