docs August 2004

docs@lists.fedoraproject.org

26 participants
57 discussions

screenshot instructions
by Tammy Fox 07 Sep '04

07 Sep '04

The instructions for taking screenshots has been posted: http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html Thanks to Karsten Wade for writing it and Paul W. Friends for editing! Tammy

5 30

mirror-tutorial 0.2
by Paul W. Frields 02 Sep '04

02 Sep '04

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

4 8

DocBook/Emacs/psgml Quickstart Guide: update
by Mark Johnson 31 Aug '04

31 Aug '04

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

2 2

Rough start...
by D＠7＠k|N& 31 Aug '04

31 Aug '04

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

5 15

taking screenshots - new section for Documentation Guide (was installation guide)
by Karsten Wade 31 Aug '04

31 Aug '04

(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-quai… 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-screen… 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

5 19

Possibly stupid question...
by D＠7＠k|N& 31 Aug '04

31 Aug '04

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

4 5

common opening sections (was Re: Style guide)
by Karsten Wade 31 Aug '04

31 Aug '04

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-ins… - 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

3 2

Re: installation guide
by Stuart Ellis 31 Aug '04

31 Aug '04

> 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

5 10

Fwd: [Bug 131233] New: Tutorial About Installing a Simple Gateway Server
by Dashamir Hoxha 31 Aug '04

31 Aug '04

4 5

Hardening Tutorial Outline added to bug 129957
by D＠7＠k|N& 30 Aug '04

30 Aug '04

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

2 1

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

2004

2003

2002

docs August 2004