mirror-tutorial 0.2
by Paul W. Frields
The updated version, hopefully ready for editorial, is available at
Bugzilla #130125. Major issues:
1. I need someone to contribute sections on apt. I don't use it, only
up2date with the yum backend. Note that the tutorial is purposely *not*
designed to be a tutorial for how to use yum and apt. The only reason
they are mentioned is in the context of providing a backend for up2date
on both the server and the client side. As it stands, the tutorial
fulfills its mission, but it does not cover the apt part, only yum.
2. There is a technical question in there about using a directory
containing ISO loopback mount points (disc1/, disc2/, etc.) via NFS for
system-config-packages. Anyone know the answer?
3. For those only willing to browse the results, the nightly HTML build
will be available tomorrow at <http://docs.frields.org>.
I need an editor; anyone willing to bear the pain?
--
Paul W. Frields, RHCE
18 years, 9 months
DocBook/Emacs/psgml Quickstart Guide: update
by Mark Johnson
Hi All,
I'll re-post here the proposed timeline/outline for the
DocBook/Emacs/psgml Quickstart Guide that I put into bugzilla.
Thanks to Tammy's helpful poking:), I've now proposed a timeline for
the DocBook/Emacs/psgml Quickstart Guide. It's recorded in bugzilla:
https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=130032
But, to get the ideas into y'all's brains asap, I'll post my
bugzilla entry here:
-------===========================-------
> From Tammy Fox <tfax.redhat.com>:
> Mark, can you provide an outline of this or a time frame?
Sure.
Since I'm doing RedHat work this weekend, I'll do some fedora doc
work next week.
How about I supply a draft outline (or doc) by Tuesday 8/30, collect
bugs/feedback, and supply a pseudo-complete outline by Friday, 9/03.
Then, provide a relatively complete document draft by Wednesday,
9/08, for everyone to critique.
From there, I would say, give me another week to submit a revised
document based on feedback, though I may be able to produce this
version sooner. In other words, I submit a usable/postable version
by Wednesday, 9/15.
I then go on vacation from 9/18 - 9/25.
Sound reasonable? (I'm working on it as I type this, FWIW.)
-------===========================-------
You can also read the bugzilla report yourself:
https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=130032
To stick to this timeline, I'll need some quick turn-around
editorial feedback. Hope we can get this out the door on schedule...
Cheers,
Mark
--
----------------------------------------------------------
Mark Johnson <mjohnson(a)redhat.com>
OS Product Documentation Group
Engineering, Red Hat, Inc. <http://www.redhat.com>
Tel: 919.754.4151 Fax: 919.754.3708
GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242
18 years, 9 months
Rough start...
by D@7@k|N&
Hi all.
I've been doing some work on the hardening tutorial and I've gotten to
the point where I have a few questions.
First of all, do I need to do anything to the bugzilla report to show
that work is actually being done on this guide?
I've tried writing in emacs, and I feel like I'm fighting the program so
much that I haven't been able to write any of the actual tutorial. So,
I did some work in Kate, and am trying to back port it with the XML tags
to make it fit the model. I followed the steps in the Doc Guide for
setting up emacs, and I think I got it right, but tag completion, and
coloring, etc. doesn't seem to be really intuitive.
Anyhow, I've taken a look at the CVS stuff, and thought that the Install
Guide my be a good one to use as an example, but that looks like a WIP.
So, I took a look at the Doc Guide, and that's a little more complete.
The layout of the Doc Guide implies that each chapter should be a
separate document. Is this true? Or, if you build one monolithic
document, will the Makefile parse all of the info correctly so that the
different chapters break out into different pages?
Finally, once I get documents complete, what's the best way to submit
stuff to my editor? CVS? Bugzilla? Email? What items should be
included in the submission?
Thanks for hand-holding me right now. Once I get the hang of it, things
should be a little easier, and I should be a little more prolific.
After looking at the Doc Guide, writing in emacs/XML doesn't seem so
daunting, so hopefully that won't be as much of an issue as I continue.
Thanks.
-Charlie
--
--
-=D@7@k|N&=-
<== dataking's pgp ==>
9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263
18 years, 9 months
taking screenshots - new section for Documentation Guide (was installation guide)
by Karsten Wade
(note message id intentionally broke to start new thread)
On Fri, 2004-08-27 at 16:33, Karsten Wade wrote:
> For expediency, I'm prepared to just submit the patch to the Doc Guide,
> rolling in some other dangling issues I can include. Tammy would see
> the CVS report and can address any mistakes and expand/modify.
Darn that cowboy mentality!
For those who chomp at the bit, you can see that I am the same myself.
The above is a perfect example. Even I get impatient at process, though
I recognize we need it more than I need to feel comfortable.
1. I don't own the document, although Tammy said I could do some minor
bugfixes and commit them to CVS. What I just wrote is a whole new
<section> not a minor fix, so that requires a new bug for tracking work
on the Documentation Guide:
https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131160
with an attachment of a diff against current CVS and then ....
2. An editor to look it over, which can be the first person who grabs it
and confirms what I did, and who can then move it on to block bug #
129722 (ready to publish) for Tammy (in her role as a document owner) to
pick up and commit to CVS, then (in the role of website maintainer)
update f.r.c/participate/documentation-guide/.
To make this easier, I have opted to host this as a DRAFT version at the
following URL:
http://people.redhat.com/kwade/patches/fedora-docs/documentation-guide-qu...
The editor will want to a) wordsmith, and b) check the technical
details, such as steps and information shown. Also, a check of the
DocBook XML is in order.
Note thought that I broke rules from the Documentation Guide:
1. I used a meaningful ID for <sect1>, dropping the location and section
specific information. At this point, the most legitimate debate is
between "similar-to-title" and "s.similar.to.title", the latter being
Norm Walsh's current usage.
2. My <screen> tags themselves are not flush left, although the content
is. I think that information described on this page:
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-scre...
is a legacy SGML problem. My builds show that the following:
<screen>
foo
</screen>
<screen>
foo
</screen>
<screen>
foo
</screen>
renders as:
foo
foo
foo
Obviously the contents of the <screen/> are highly sensitive to
whitespace issues, and in fact could perhaps be CDATA containers instead
to totally make them ignored by the toolchain. Either way, I don't
think the <screen> tags need to be flush left, nor the the
<computeroutput/> container. I'd like to recommend this for a change in
the Documentation Guide, and will file a bugzilla with patch if there is
no technical objection.
- Karsten, off to see Run Lola Run at http://www.thespoon.com/drivein/
--
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
18 years, 9 months
Possibly stupid question...
by D@7@k|N&
Since I have been working on the hardening tute, I've been doing so with
the Docs Guide open, so I have an immediate reference for the tags that
I should be using. I noticed something, that other people may have
noticed, but I don't really understand the point of. The
<guibutton></guibutton>, <guilabel>, <guimenu>, <guimenuitem>,
<application>, and several other tags, all seem to just make the text
bold. Is there a reason that these aren't more defined? (Something
really could would be to id the guimenu buttons, and have the tag insert
the graphic for that button, etc.) Without the more differentiating
characteristics, what is the point of using different tags?
-Charlie
--
--
-=D@7@k|N&=-
<== dataking's pgp ==>
9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263
18 years, 9 months
common opening sections (was Re: Style guide)
by Karsten Wade
I think the below sounds reasonable and correct. With this kind of
stuff, it's just so automatic for me to include it, and I haven't really
sat down to analyze a tutorial structure to break it out more clearly.
I definitely think we need these common sections.
On Sat, 2004-08-28 at 19:33, Mark Johnson wrote:
> As I'm working on the Emacs/DocBook Quickstart guide, it occurs to
> me that that perhaps we should provide some required sections in the
> beginning of the document that would be intended to address such
> questions as (realizing that the following are not logically
> independent):
Since it sounds as if you are writing a set of these yourself, how about
if you complete your version and submit it as a draft for a common,
single <section> containing file. That will be kept in
fedora-docs/common. When we see your version in action, we can then
make any tweaks/suggestions, and then make it part of any document.
Few specific thoughts at this point:
> - intended audience
> - scope of this document
> - what this document addresses
> - what this docuemt does not address
> - goals of this document (a pseudo re-phrasing of the above)
> - contributors to this document
> - scope of this document
> - [....]???
That's pretty much it; just a sentence or two each, so this is about one
paragraph right at the start.
> My feeling is that context that the above info provide are very
> important, in that they allow the reader to quickly assess the scope
> of the document and, hence, whether it is worth their time to read
> it. Past experience has shown that the mandatory inclusion of this
> sort of info a document/tutorial provides valuable info to the reader.
Agreed
> My points (and questions), are then:
>
> - What, if any, should be the required metadata content for standard
> fedora docs (which at this point are tutorially structured)?
>From Dave's response, I'm not sure I know what kind of metadata you are
talking about. Is this part of the DocBook structure?
> Put another way, should we require some initial sections titled, e.g.:
>
> - intended audience
>
> - goals of this document (N.B. these are different from the scope as
> described below), and also provide a basis from which readers can
> file bug erports. E.g. Bug pointing out how doc doesn't achieve a
> given goal.
>
> - scope of this document (what it does/doesn't addressed in this
> section.
>
> - contributors
Having a contributors <section> (as part of the single, common file)
would be a good way to handle long lists of contributors. Otherwise, I
would recommend hacking the stylesheet so we didn't have a full page of
authors as the standard DB stylesheets does for the <authorgroup>.
Another section we might consider is a document conventions section
[1]. Is this appropriate/necessary/useful for tutorial sized
documents? It's probably also unnecessary for right now, but something
we could develop. FWIW, I'm intere
[1] E.g.
http://www.redhat.com/docs/manuals/enterprise/RHEL-3-Manual/x8664-multi-i...
- Karsten
--
Karsten Wade, RHCE, Tech Writer
a lemon is just a melon in disguise
http://people.redhat.com/kwade/
gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41
18 years, 9 months
Re: installation guide
by Stuart Ellis
> I meant to reply to this thread but didn't get a chance when it was
> fresh. Now it is old and smelly, but we still love it just the same. :-)
> Let's get this one on the road. I would like to put the Style Guide to
> the side (not the same as on the back burner) while we work on this. The
> Style Guide is a great thing and necessary, but not as important as
> having an Installation Guide.
> I think handing out chapter assignments (or alternately, taking
> volunteers for chapters) would give everyone an idea of authoring skill
> levels. It would also mean we could put the process doc to the test, and
> beyond that, give us good ideas to address in the Style Guide.
I was wondering about this - I couldn't find details on the tracking bug
or the list archives.
I'd be interested in helping, if volunteers are needed. Looking at the
TOC I wouldn't be able to test dual-boot or partitioning (no RAIDable
systems), but could probably tackle any of the other parts as required.
Now away until Monday, can pick up from there.
--
Stuart Ellis
s.ellis(a)fastmail.co.uk
18 years, 9 months
Hardening Tutorial Outline added to bug 129957
by D@7@k|N&
Attaching outline for review by the group (to bug, not here).
Group:
This is the direction I'm heading. I'm thinking that I might need to
add a few more things, but this should be a good start. I think that
kernel compilation should be somewhere in there, but considering the
recent (ongoing) discussion of magnitude (guide vs. tutorial) on the
lists, I'll leave it here for now. Thoughts, suggestions, additions,
critique....all are welcome. I'll be posting the Intro and Chapter 1
xml docs, as soon as I have them available (which should be soon).
https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129957
--
--
-=D@7@k|N&=-
<== dataking's pgp ==>
9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263
18 years, 9 months