docs ideas, dream big

[Stuart Ellis]

On Mon, 2005-08-22 at 15:33 +0200, Peter Boy wrote:

> 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).

<snip>

There's a lot of very good ideas and arguments here. Below is my attempt
to summarize them so that hopefully other people will come in and start
discussing the specifics in more detail. I haven't added any comments on
this mail.


- List user documentation on a separate page from process documentation,
since only contributors and potential contributors care about process
documentation.

- Possibly have two classes of documentation:

* Complete documents and tutorials
* Short FAQ items or technical notes that people can write as part of a
framework (in the same way that the Release Notes are made up of many
individual self-contained notes)

- Organize documents into categories. Some documents may appear under
more than one heading.

- For each category, have a general set of guidelines that applies to
relevant documents to assist contributors (e.g. documents on server
software should show the use of Fedora management tools where possible).

- For each category, have a list of suggested topics that contributors
could address (e.g. "Developing with Fedora" has the suggested topics
Packaging, Python, Java).

- A provisional list of categories (I've amended the titles slightly
from the original for clarity):

* Release Notes
* Installation Guide
* Start Using Fedora
* Using the Desktop
* Using Fedora as a Server
* Emerging Technologies
* Software Development with Fedora
* System Administration
* Network Configurations (Home network, network with Stateless Linux
etc.)
* Miscellaneous (Jargon Buster)

* FDP Process Documentation

Some of these categories are single, but large "Guides".

-- 

Stuart Ellis

stuart at elsn.org

Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

GPG key ID: 7098ABEA
GPG key fingerprint: 68B0 E291 FB19 C845 E60E  9569 292E E365 7098 ABEA 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20050822/9b3d0ee3/attachment.sig>