Getting started with documentation

[Jesse Keating]

On Friday 16 January 2004 08:41, Jonas Pasche wrote:
> Okay, so let's start collecting information:
>
> - Who has write access to the site / whom should I send new content?

Eric Rostetter, Warren Togami,and I have write access to the site.  The 
site is held in CVS, but no anon access just yet (weird bug I haven't 
tracked down).  If your content changes and such prove good, I can 
arrange for you to have write access to the CVS repository as well.

> - Who wants to help writing?

I can't write much, but I can answer questions about the project and 
it's direction.

> - 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 is more straightforward if there is only a small
> group who manages it, to avoid what I call the "wiki effect": A
> couple of pages, some very very detailed, some still to be written,
> some pages that are more a bookmark collection than written content,
> and everything in different writing styles and quality.

I think a private version held on your site that is reviewed by a select 
few would be good.  For now you can run things through me and Eric.  
Right now Eric is the main web developer for this project.

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

The pages are html/php (php is just for the dynamic includes at 
to/bottom/right/left).  The pages themselves are held in CVS.  I have 
yet to develop an automated way to get whats in CVS out to the public 
web.  Currently it's a manual process done by either Eric or I.

> 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? ...
>
>    I think I can prepare this part well, because I know most things
>    about it.

Great, this is very much needed information.  We do now have an announce 
mailing list.  
http://www.redhat.com/mailman/listinfo/fedora-legacy-announce

This list is read-only and it's where update announcements will be 
posted.

> 2) Developers: How can I participate? ...
>
>    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.

Correct.  Warren posted his package submission steps a while ago, I 
provided feedback on how they should be modified to be Legacy specific.  
It's in this mailing list's archives.  Perhaps grabbing his process, 
applying my changes, and making it static content on our 
fedoralegacy.org website would be best.

> 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 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?

Most the infrastructure for contribution is in the air unfortunately.  
We got a late start on the project, mostly due to my fault.  The build 
server was late in being turned over to me, and it's still not ready 
for public use, so we're doing things by hand.  Warren was awesome and 
stepped in while I was otherwise busy and got some things rolling.  
We're almost ready to be self contained, but we do still need some 
help.  I think the biggest step right now is getting the packages 
published and signed.  I do believe there are packages in bugzilla that 
have gotten the appropriate QA and are ready to be published.  Warren 
and I need to work out a way to get these published and signed.   The 
announce list was one of the roadblocks in getting this done.  Now that 
we have the list, I urge everybody to sign up as we'll be pushing out 
packages soon.

> Based on this, we should also work on the "Participate" section,
> telling a bit more than "We need every helping hand we can get" -
> maybe more in the style of "We need somebody who regularly checks the
> Bugzilla LEGACY queue, downloads packages and test if they build and
> install cleanly, then giving feedback on Bugzilla. We need somebody
> who watches the Red Hat Announcement list for updates that are
> important for Fedora Legacy, does a quick analysis of the update and
> informs the people on what is to 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.

Agreeable.  Specific tasks with shortened steps would be best in this 
case.  While fedora.us has a great deal of information, it is rather 
difficult to digest.  Breaking it into manageable chunks for 
individuals to do individual tasks would be best for our website.

Please keep the questions coming, this is great!

-- 
Jesse Keating RHCE MCSE (geek.j2solutions.net)
Fedora Legacy Team      (www.fedora.us/wiki/FedoraLegacy)
Mondo DevTeam           (www.mondorescue.org)
GPG Public Key          (geek.j2solutions.net/jkeating.j2solutions.pub)
 
Was I helpful?  Let others know:
 http://svcs.affero.net/rm.php?r=jkeating
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: signature
URL: <http://listman.redhat.com/archives/fedora-legacy-list/attachments/20040116/6bd0c6e2/attachment.sig>