Getting started with documentation

[Eric Rostetter]

Quoting Jonas Pasche <mail at jonaspasche.de>:

> Okay, so let's start collecting information:
>
> - Who has write access to the site / whom should I send new content?

Jesse, myself, probably warren?

> - Who wants to help writing?

You may be on your own :(

> - Who wants to review content before publishing? Or would it be better
>   to pre-publish content on my own site first and let it be reviewed by
>   any list members who are willing to? From my point of view the process

Either is fine.  I can review/clean-up content if you want.  Or posting
for list review is fine.

> - To the webmaster: In what file format is new content expected - plain
>   text? HTML? Or are these pages generated through some kind of CMS?

Either plain text or html.  PHP is okay if used for a reason.  No CMS system
as of now.  We do have it in CVS.  There's a link on the web page (upper
right "news" section) to info about the cvs.

> Regarding the content itself - from my point of view we need two parts
> of documentation as a start:
>
> 1) End users: What is Fedora Legacy? What can I do to keep my system up
>    to date? Where can I find security advisories? ...

What it is we try to cover in the "about" section.  How to keep it up to
date we try to cover somewhat in the "download" section.  Where can I find
advisories has yet to be determined as far as I know.  I think an
announcement mailing list is in the cooker but not done yet?

>    I think I can prepare this part well, because I know most things
>    about it.

Start with what is there, and add on or rewrite it.

> 2) Developers: How can I participate? ...

This needs a lot of work!

>    This part would be harder for me, because I'm not a developer.
>    Besides that, package submission and QA mainly works as with regular
>    Fedora extra packages (I think so?!), which are documented on the
>    Wiki, however, in a very short form. For legacy packages, the process
>    should be easier, because some parts (e.g. writing completely new
>    %pre[un] and %post[un] scripts, package name choosing, desktop entry
>    choosing) are simply not needed for legacy packages. Anyway, I need
>    assistance with this part from somebody who knows this process very
>    well to tell me what is needed and what isn't.

Yes, me too.  I'm going to steal some of the fedora stuff for our site,
and hope it gets refined from there.  But any help from anyone is welcome.

> A word about participation in general: There is a short list on
> fedoralegacy.org what can be done, but few information how the make the
> first steps to actually start helping. In turn, there are quite a couple

Yes, that page is very bad.  Needs lots of help.

> of self introductions on the list, so there are people to do work, but
> nothing has yet effectively led to officially published packages, so
> obviously people are missing directions on what to do and how to it - or
> am I missing another reason?

I think direction/directions are certainly missing.  As are definitions
as to what certain steps in the process even mean.

> Based on this, we should also work on the "Participate" section, telling

Yes, please do!

> be done", and so on. Meaning, more a kind of a job description, to allow
> interested people to judge what they can to and what they can't. For
> example, maybe I'd be technically able to "do QA" and simply don't know
> it, because I don't know what exactly "doing QA" means, being confused
> by 25 steps in 7 sections, just to mention the PackageSubmissionQAPolicy
> document - and I'm sure I only have to do a few of them, regarding
> legacy packages.

Yes, exactly.  Great idea linking it to a "job description" style.  Sounds
great.

> Jonas

--
Eric Rostetter