docs January 2009

docs@lists.stg.fedoraproject.org

45 participants
80 discussions

curl instead of wget
by Rahul Sundaram 05 Jan '09

05 Jan '09

Hi, In documentation, wherever we are using wget, it is probably better to use curl instead since wget is not installed by default on the Live CD while curl is. Just a thought. Rahul

5 7

Re: PATCH[1/1] Linux Security Guide
by Magnus Glantz 04 Jan '09

04 Jan '09

My €5 as an non US citizen. I do not feel comfortable with a guide that seems almost completely ripped off published US military/government documents. Also, way to much direct references to US military/government web pages and documents. My though is that this needs a complete re-write. Best regards, //M > > Today's Topics: > > 1. PATCH[1/1] Linux Security Guide: edit of > General_Principles.xml (Murray McAllister) > 2. Re: PATCH[1/1] Linux Security Guide: edit of > General_Principles.xml (Murray McAllister) > > > ---------------------------------------------------------------------- > > Message: 1 > Date: Sat, 3 Jan 2009 14:20:01 +1000 > From: "Murray McAllister" <murray.mcallister(a)gmail.com> > Subject: PATCH[1/1] Linux Security Guide: edit of > General_Principles.xml > To: "For participants of the Documentation Project" > <fedora-docs-list(a)redhat.com> > Cc: sparks(a)fedoraproject.org > Message-ID: > <95f1114b0901022020n3fe734b5icd4792d9e3b78c71(a)mail.gmail.com> > Content-Type: text/plain; charset=ISO-8859-1 > > Hi, > > I found some motivation this morning, so I tried to review > "...community/fc11/en-US/General_Principles.xml". > > If it looks okay, it would be great if a security person (I made minor > additions) and a writer person could check it for accuracy. > > > ---- > > --- community/fc11/en-US/General_Principles.xml 2009-01-03 > 13:44:01.000000000 +1000 > +++ new/community/fc11/en-US/General_Principles.xml 2009-01-03 > 13:42:09.000000000 +1000 > @@ -5,88 +5,70 @@ > <chapter id="chap-Security_Guide-General_Principles_of_Information_Security"> > <title>General Principles of Information Security</title> > <para> > - The United States' <ulink url="www.nsa.gov">National Security > Agency</ulink> (NSA) provides hardening guides and hardening tips for > many different operating systems to help government agencies, > businesses, and individuals help secure their system against attacks. > In addition to specific settings to change, a set of general > principles have been developed to give you a high level view of > information security. > + The following general principals provide an overview of good > security practices: > </para> > - <section id="sect-Security_Guide-General_Principles_of_Information_Security-General_Principles"> > - <title>General Principles</title> > - <itemizedlist> > - <listitem> > - <para> > - Encrypt all data transmitted over the network. Encrypting > authentication information (such as passwords) is particularly > important. > - </para> > - </listitem> > - <listitem> > - <para> > - Minimize the amount of software installed and running in order to > minimize vulnerability. > - </para> > - </listitem> > - <listitem> > - <para> > - Use security-enhancing software and tools whenever available (e.g. > SELinux and IPTables). > - </para> > - </listitem> > - <listitem> > - <para> > - Run each network service on a separate server whenever possible. > This minimizes the risk that a compromise of one service could lead to > a compromise of others. > - </para> > - </listitem> > - <listitem> > - <para> > - Maintain user accounts. Create a good password policy and enforce > its use. Delete unused user accounts. > - </para> > - </listitem> > - <listitem> > - <para> > - Review system and application logs on a routine basis. Send logs > to a dedicated log server. This prevents intruders from easily > avoiding detection by modifying the local logs. > - </para> > - </listitem> > - <listitem> > - <para> > - Never login directly as root, unless absolutely necessary. > Administrators should use sudo to execute commands as root when > required. The accounts capable of using sudo are specified in > /etc/sudoers, which is edited with the visudo utility. By default, > relavent logs are written to /var/log/secure. > - </para> > - </listitem> > - </itemizedlist> > - </section> > + <itemizedlist> > + <listitem> > + <para> > + encrypt all data transmitted over networks to help prevent > man-in-the-middle attacks and eavesdropping. It is important to > encrypt authentication information, such as passwords. > + </para> > + </listitem> > + <listitem> > + <para> > + minimize the amount of software installed and running services. > + </para> > + </listitem> > + <listitem> > + <para> > + use security-enhancing software and tools, for example, > Security-Enhanced Linux (SELinux) for Mandatory Access Control (MAC), > Netfilter iptables for packet filtering (firewall), and the GNU > Privacy Guard (GnuPG) for encrypting documents. > + </para> > + </listitem> > + <listitem> > + <para> > + if possible, run each network service on a separate system to > minimize the risk of one compromised service being used to compromise > other services. > + </para> > + </listitem> > + <listitem> > + <para> > + maintain user accounts: create and enforce a strong password > policy; delete unused user accounts. > + </para> > + </listitem> > + <listitem> > + <para> > + routinely review system and application logs. By default, > security-relevant system logs are written to > <filename>/var/log/secure</filename> and > <filename>/var/log/audit/audit.log</filename>. Note: sending logs to a > dedicated log server helps prevent attackers from easily modifying > local logs to avoid detection. > + </para> > + </listitem> > + <listitem> > + <para> > + never log in as the root user unless absolutely necessary. It is > recommended that administrators use <command>sudo</command> to execute > commands as root when required. Users capable of running > <command>sudo</command> are specified in > <filename>/etc/sudoers</filename>. Use the <command>visudo</command> > utility to edit <filename>/etc/sudoers</filename>. > + </para> > + </listitem> > + </itemizedlist> > <section id="sect-Security_Guide-General_Principles_of_Information_Security-Tips_Guides_and_Tools"> > <title>Tips, Guides, and Tools</title> > <para> > - Most of the above tips are very basic. Depending on your knowledge > of Linux and how comfortable you are with modifying your system, some > changes could be made to help make your installation more secure. As > mentioned above, the NSA has hardening guides and tips for securing > Red Hat Enterprise Linux 5. Likewise, the <ulink > url="http://www.disa.mil/">Defense Information Systems Agency</ulink> > (DISA) has an <ulink url="iase.disa.mil">Information Assurance Support > Environment</ulink> in which they publish checklists and tests for > verifying the security of your system. The documents from the NSA are > a good read for anyone familiar with Linux while the information from > DISA is extremely specific and advanced knowledge of Unix/Linux would > be a great benefit. Links to these documents are listed below. We will > try to pull some of the larger items out of these documents and > explain how to implement them in Fedora and why they are important. In > addition to documentation, DISA has made available SRR scripts that > allow an administrator to check specific settings on a system quickly. > The SRR scripts will provide an XML-formatted report listing any known > vulnerable settings that you have on your system. > + The United States' <ulink url="http://www.nsa.gov/">National > Security Agency (NSA)</ulink> provides hardening guides and tips for > many different operating systems, to help government agencies, > businesses, and individuals secure their systems against attack. The > following guides (in PDF format) provide guidance for Red Hat > Enterprise Linux 5: > </para> > - </section> > - <section id="sect-Security_Guide-General_Principles_of_Information_Security-NSA_Documents"> > - <title>NSA Documents</title> > <itemizedlist> > - <listitem> > - <para> > - <ulink > url="www.nsa.gov/notices/notic00004.cfm?Address=/snac/os/redhat/rhel5-pamphlet-i…">Hardening > Tips for the Red Hat Enterprise Linux 5 (PDF)</ulink> > - </para> > - </listitem> > - <listitem> > - <para> > - <ulink > url="www.nsa.gov/notices/notic00004.cfm?Address=/snac/os/redhat/rhel5-guide-i731…">Guide > to the Secure Configuration of Red Hat Enterprise Linux 5 > (PDF)</ulink> > - </para> > - </listitem> > + <listitem> > + <para> > + <ulink url="http://www.nsa.gov/notices/notic00004.cfm?Address=/snac/os/redhat/rhel5-pam…">Hardening > Tips for the Red Hat Enterprise Linux 5</ulink> > + </para> > + </listitem> > + <listitem> > + <para> > + <ulink url="http://www.nsa.gov/notices/notic00004.cfm?Address=/snac/os/redhat/rhel5-gui…">Guide > to the Secure Configuration of Red Hat Enterprise Linux 5</ulink> > + </para> > + </listitem> > </itemizedlist> > - </section> > - <section id="sect-Security_Guide-General_Principles_of_Information_Security-DISA_IASE_Documents"> > - <title>DISA IASE Documents</title> > - <itemizedlist> > - <listitem> > - <para> > - <ulink url="iase.disa.mil/stigs/stig/index.html">Security > Technical Implementation Guides</ulink> (STIG) Scroll down to the Unix > STIG > - </para> > - </listitem> > - <listitem> > - <para> > - <ulink > url="iase.disa.mil/stigs/checklist/index.html">Security > Checklists</ulink> Scroll down to the Unix Security Checklists > - </para> > - </listitem> > - <listitem> > - <para> > - <ulink url="iase.disa.mil/stigs/SRR/unix.html">Unix Security > Readiness Review Evaluation Script</ulink> > - </para> > - </listitem> > - </itemizedlist> > - </section> > - </chapter> > - > + <para> > + The <ulink url="http://www.disa.mil/">Defense Information Systems > Agency (DISA)</ulink> provides documentation, checklists, and tests to > help secure your system (<ulink > url="http://iase.disa.mil/index2.html">Information Assurance Support > Environment</ulink>). The <ulink > url="http://iase.disa.mil/stigs/stig/unix-stig-v5r1.pdf">UNIX SECURITY > TECHNICAL IMPLEMENTATION GUIDE</ulink> (PDF) is a very specific guide > to UNIX security - an advanced knowledge of UNIX and Linux is > recommended before reading this guide. > + </para> > + <para> > + The DISA <ulink > url="http://iase.disa.mil/stigs/checklist/unix_checklist_v5r1_15_20081215.ZIP">UNIX > Security Checklist Version 5, Release 1.15</ulink> provides a > collection of documents and checklists, ranging from the correct > ownerships and modes for system files, to patch control. > + </para> > + <para> > + Also, DISA has made available <ulink > url="http://iase.disa.mil/stigs/SRR/unix.html">UNIX SPR > scripts</ulink> that allow administrators to check specific settings > on systems. These scripts provide XML-formatted reports listing any > known vulnerable settings. > + </para> > + </section> > +</chapter> > \ No newline at end of file > > ---- > > The link for "Hardening Tips for the Red Hat Enterprise Linux 5" does > not work after accepting the license agreement. I have mailed > <nsapao(a)nsa.gov>. > > Cheers. > > > > ------------------------------ > > Message: 2 > Date: Sat, 3 Jan 2009 14:29:55 +1000 > From: "Murray McAllister" <murray.mcallister(a)gmail.com> > Subject: Re: PATCH[1/1] Linux Security Guide: edit of > General_Principles.xml > To: "For participants of the Documentation Project" > <fedora-docs-list(a)redhat.com> > Message-ID: > <95f1114b0901022029s29abea16h75e87c93160ee001(a)mail.gmail.com> > Content-Type: text/plain; charset=ISO-8859-1 > > I did not test how this would send, sorry. Use: > > wget http://mdious.fedorapeople.org/patches/General_Principles.xml.patch > > > > ------------------------------ > > -- > fedora-docs-list mailing list > fedora-docs-list(a)redhat.com > https://www.redhat.com/mailman/listinfo/fedora-docs-list > > End of fedora-docs-list Digest, Vol 59, Issue 4 > ***********************************************

3 2

rpm-info to publican conversion
by Paul W. Frields 04 Jan '09

04 Jan '09

I started a small project to simplify some of the metadata conversion process from our old-style, FDP toolchain-created docs into Publican: http://pfrields.fedorapeople.org/projects/rpminfo-to-publican/ It's not a code repository, just a script and some XSL stylesheets I prepared. It's far from bulletproof (maybe a little tetchy, actually), so patches gratefully accepted. The procedure: 1. Create a bare-bones Publican doc of the type you want, preferably matching the original (book, article, or set), with brand "fedora" and a name like "This_Guide_Name". 2. cd This_Guide_Name tar xzf /path/to/rpminfo-to-publican.tar.gz sh rpminfo-to-publican.sh /path/to/rpm-info.xml 3. Add YEAR and HOLDER entities to <LANG>/This_Guide_Name.ent as usual. The XSL stylesheets properly import names of authors, revision history, and other document metadata to the appropriate files, and backup the old ones in an 'orig/' folder. You should run this procedure *before* you put additional data in these files. -- Paul W. Frields http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 http://redhat.com/ - - - - http://pfrields.fedorapeople.org/ irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug

3 3

Man page coverage
by Basil Mohamed Gohar 04 Jan '09

04 Jan '09

I'm really sorry I'm so late on all of this, but just after Karsten admitted me to the Docs project, I caught a fever, cough, indigestion - the whole nine yards. Soon after I recovered, the submarine cables connecting Egypt (where I am for a few months) were cut, so we were having very unreliable Internet service for the following weekend. Anyway, excuses aside, the task I was hoping to tackle involved establishing a sub-project to do complete man-page coverage of existing packages & applications within Fedora. The discussion started over on the fedora-devel list, and it seemed that I was the most enthusiastic about undertaking the project, so that's what I'd like to propose, but here within the Docs project. I outlined a few general steps, and you can read up here: https://www.redhat.com/archives/fedora-devel-list/2008-December/msg00023.ht… To save you a trip, I'll repost the steps here: 1) Identify which packages are missing man pages altogether in Fedora -- these should get top priority -- we can see if Debian or other projects already have some -- acceptable-licensing-pending, of course 2) Identify which packages having sub-par man pages -- after fulfilling 1), this should be the next priority -- similar methodology to 1), find ones that already exist first 3) Develop a "stub" template for packages that have no man pages available -- at least we can include command-line arguments, authorship, web links for more info, etc. -- at first this isn't much better than -h/--help, but we can at least let it be a start 4) Once we have all of this information prepared, then we can get to work on forming a project around this group, preparing a page in the wiki with the packages that need man pages or whose man pages need improvement, etc. 5) ??? 6) Profit! So, right now, I'm very green when it comes to working on open-source projects. I've been using Fedora for a while, but I still can be somewhat ignorant when it comes to doing some things. I'm a PHP developer by trade, so I'm not clueless, but you get my point. What I could use help with from the more experienced would be, for example, a way to identify the existence of man pages for packages. For example, is it enough to have a single man page for a package, or do we want a man page for every executable file? I'm willing to do a fair share of the work, but I also hope some others are willing to help out where they can as well. ;) Okay, that's enough for one e-mail. I just wanted to get the ball rolling and get started on some of these steps, and see what else anyone else would like to share in terms of ideas.

1 1

PATCH[1/1] Linux Security Guide: edit of General_Principles.xml
by Murray McAllister 02 Jan '09

02 Jan '09

Hi, I found some motivation this morning, so I tried to review "...community/fc11/en-US/General_Principles.xml". If it looks okay, it would be great if a security person (I made minor additions) and a writer person could check it for accuracy. ---- --- community/fc11/en-US/General_Principles.xml 2009-01-03 13:44:01.000000000 +1000 +++ new/community/fc11/en-US/General_Principles.xml 2009-01-03 13:42:09.000000000 +1000 @@ -5,88 +5,70 @@ <chapter id="chap-Security_Guide-General_Principles_of_Information_Security"> <title>General Principles of Information Security</title> <para> - The United States' <ulink url="www.nsa.gov">National Security Agency</ulink> (NSA) provides hardening guides and hardening tips for many different operating systems to help government agencies, businesses, and individuals help secure their system against attacks. In addition to specific settings to change, a set of general principles have been developed to give you a high level view of information security. + The following general principals provide an overview of good security practices: </para> - <section id="sect-Security_Guide-General_Principles_of_Information_Security-General_Principles"> - <title>General Principles</title> - <itemizedlist> - <listitem> - <para> - Encrypt all data transmitted over the network. Encrypting authentication information (such as passwords) is particularly important. - </para> - </listitem> - <listitem> - <para> - Minimize the amount of software installed and running in order to minimize vulnerability. - </para> - </listitem> - <listitem> - <para> - Use security-enhancing software and tools whenever available (e.g. SELinux and IPTables). - </para> - </listitem> - <listitem> - <para> - Run each network service on a separate server whenever possible. This minimizes the risk that a compromise of one service could lead to a compromise of others. - </para> - </listitem> - <listitem> - <para> - Maintain user accounts. Create a good password policy and enforce its use. Delete unused user accounts. - </para> - </listitem> - <listitem> - <para> - Review system and application logs on a routine basis. Send logs to a dedicated log server. This prevents intruders from easily avoiding detection by modifying the local logs. - </para> - </listitem> - <listitem> - <para> - Never login directly as root, unless absolutely necessary. Administrators should use sudo to execute commands as root when required. The accounts capable of using sudo are specified in /etc/sudoers, which is edited with the visudo utility. By default, relavent logs are written to /var/log/secure. - </para> - </listitem> - </itemizedlist> - </section> + <itemizedlist> + <listitem> + <para> + encrypt all data transmitted over networks to help prevent man-in-the-middle attacks and eavesdropping. It is important to encrypt authentication information, such as passwords. + </para> + </listitem> + <listitem> + <para> + minimize the amount of software installed and running services. + </para> + </listitem> + <listitem> + <para> + use security-enhancing software and tools, for example, Security-Enhanced Linux (SELinux) for Mandatory Access Control (MAC), Netfilter iptables for packet filtering (firewall), and the GNU Privacy Guard (GnuPG) for encrypting documents. + </para> + </listitem> + <listitem> + <para> + if possible, run each network service on a separate system to minimize the risk of one compromised service being used to compromise other services. + </para> + </listitem> + <listitem> + <para> + maintain user accounts: create and enforce a strong password policy; delete unused user accounts. + </para> + </listitem> + <listitem> + <para> + routinely review system and application logs. By default, security-relevant system logs are written to <filename>/var/log/secure</filename> and <filename>/var/log/audit/audit.log</filename>. Note: sending logs to a dedicated log server helps prevent attackers from easily modifying local logs to avoid detection. + </para> + </listitem> + <listitem> + <para> + never log in as the root user unless absolutely necessary. It is recommended that administrators use <command>sudo</command> to execute commands as root when required. Users capable of running <command>sudo</command> are specified in <filename>/etc/sudoers</filename>. Use the <command>visudo</command> utility to edit <filename>/etc/sudoers</filename>. + </para> + </listitem> + </itemizedlist> <section id="sect-Security_Guide-General_Principles_of_Information_Security-Tips_Guides_and_Tools"> <title>Tips, Guides, and Tools</title> <para> - Most of the above tips are very basic. Depending on your knowledge of Linux and how comfortable you are with modifying your system, some changes could be made to help make your installation more secure. As mentioned above, the NSA has hardening guides and tips for securing Red Hat Enterprise Linux 5. Likewise, the <ulink url="http://www.disa.mil/">Defense Information Systems Agency</ulink> (DISA) has an <ulink url="iase.disa.mil">Information Assurance Support Environment</ulink> in which they publish checklists and tests for verifying the security of your system. The documents from the NSA are a good read for anyone familiar with Linux while the information from DISA is extremely specific and advanced knowledge of Unix/Linux would be a great benefit. Links to these documents are listed below. We will try to pull some of the larger items out of these documents and explain how to implement them in Fedora and why they are important. In addition to documentation, DISA has made available SRR scripts that allow an administrator to check specific settings on a system quickly. The SRR scripts will provide an XML-formatted report listing any known vulnerable settings that you have on your system. + The United States' <ulink url="http://www.nsa.gov/">National Security Agency (NSA)</ulink> provides hardening guides and tips for many different operating systems, to help government agencies, businesses, and individuals secure their systems against attack. The following guides (in PDF format) provide guidance for Red Hat Enterprise Linux 5: </para> - </section> - <section id="sect-Security_Guide-General_Principles_of_Information_Security-NSA_Documents"> - <title>NSA Documents</title> <itemizedlist> - <listitem> - <para> - <ulink url="www.nsa.gov/notices/notic00004.cfm?Address=/snac/os/redhat/rhel5-pamphlet-i…">Hardening Tips for the Red Hat Enterprise Linux 5 (PDF)</ulink> - </para> - </listitem> - <listitem> - <para> - <ulink url="www.nsa.gov/notices/notic00004.cfm?Address=/snac/os/redhat/rhel5-guide-i731…">Guide to the Secure Configuration of Red Hat Enterprise Linux 5 (PDF)</ulink> - </para> - </listitem> + <listitem> + <para> + <ulink url="http://www.nsa.gov/notices/notic00004.cfm?Address=/snac/os/redhat/rhel5-pam…">Hardening Tips for the Red Hat Enterprise Linux 5</ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="http://www.nsa.gov/notices/notic00004.cfm?Address=/snac/os/redhat/rhel5-gui…">Guide to the Secure Configuration of Red Hat Enterprise Linux 5</ulink> + </para> + </listitem> </itemizedlist> - </section> - <section id="sect-Security_Guide-General_Principles_of_Information_Security-DISA_IASE_Documents"> - <title>DISA IASE Documents</title> - <itemizedlist> - <listitem> - <para> - <ulink url="iase.disa.mil/stigs/stig/index.html">Security Technical Implementation Guides</ulink> (STIG) Scroll down to the Unix STIG - </para> - </listitem> - <listitem> - <para> - <ulink url="iase.disa.mil/stigs/checklist/index.html">Security Checklists</ulink> Scroll down to the Unix Security Checklists - </para> - </listitem> - <listitem> - <para> - <ulink url="iase.disa.mil/stigs/SRR/unix.html">Unix Security Readiness Review Evaluation Script</ulink> - </para> - </listitem> - </itemizedlist> - </section> - </chapter> - + <para> + The <ulink url="http://www.disa.mil/">Defense Information Systems Agency (DISA)</ulink> provides documentation, checklists, and tests to help secure your system (<ulink url="http://iase.disa.mil/index2.html">Information Assurance Support Environment</ulink>). The <ulink url="http://iase.disa.mil/stigs/stig/unix-stig-v5r1.pdf">UNIX SECURITY TECHNICAL IMPLEMENTATION GUIDE</ulink> (PDF) is a very specific guide to UNIX security - an advanced knowledge of UNIX and Linux is recommended before reading this guide. + </para> + <para> + The DISA <ulink url="http://iase.disa.mil/stigs/checklist/unix_checklist_v5r1_15_20081215.ZIP">UNIX Security Checklist Version 5, Release 1.15</ulink> provides a collection of documents and checklists, ranging from the correct ownerships and modes for system files, to patch control. + </para> + <para> + Also, DISA has made available <ulink url="http://iase.disa.mil/stigs/SRR/unix.html">UNIX SPR scripts</ulink> that allow administrators to check specific settings on systems. These scripts provide XML-formatted reports listing any known vulnerable settings. + </para> + </section> +</chapter> \ No newline at end of file ---- The link for "Hardening Tips for the Red Hat Enterprise Linux 5" does not work after accepting the license agreement. I have mailed <nsapao(a)nsa.gov>. Cheers.

1 1

Problem with XML
by Eric Christensen 02 Jan '09

02 Jan '09

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Yesterday on the train, I converted part of the "Using GPG" portion of the Security Guide. I get an error when I try to "make" the book now. The error is: junk after document element at line 11, column 0, byte 739: </para> </section> <section id="sect-Security_Guide-Encryption-Using_GPG-Creating_GPG_Keys_in_GNOME"> ^ <title>Creating GPG Keys in GNOME</title> <para> at /usr/lib/perl5/vendor_perl/5.10.0/i386-linux-thread-multi/XML/Parser.pm line 187 make: *** [xml-en-US] Error 4 I've compared the file to other files that I have and I can't see any differences. Does anyone have any ideas? Thanks, Eric Christensen E-Mail: sparks(a)fedoraproject.org GPG Key: BD0C14C1 -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org iEYEARECAAYFAklc4CkACgkQfQTSQL0MFME9DACgi4e0+tilap7jwCBAF60Oq2Sv qcQAoNFpKTfM+P2BuCnpXvJMXjwGSh2p =Ip0i -----END PGP SIGNATURE-----

5 11

Maintenance/Brevity vs. Explicit Instructions
by Matthew Daniels 01 Jan '09

01 Jan '09

The other day I noticed someone mention in #fedora-docs how much of a maintenance nightmare it is to have the same user instructions replicated over multiple places. In the process of editing the UG, I've been thinking; is there a good reason that this happens, or is it just because of the way docs get tangled up over time? For example, the User Guide has multiple places where the user is instructed to install new software. I understand that there is some value in repeating the instructions every time this happens, but is it worth the nightmare is causes with maintenance and uniformity? Would it not be better to simply keep the canon set of instructions in one place (like User Guide - Managing Software) and consistently refer the user to these instructions? Just curious for everyone's opinion on this. Kinda wanted to bounce it around before I change everything. -Matthew

2 1

functional areas of Docs Project
by Karsten Wade 01 Jan '09

01 Jan '09

Thinking about our various processes, it seems a good idea to put them in functional areas. A process might be used in one or multiple parts of the project. For example, a process for requesting access to a document on fedorahosted.org is used in many functional areas, such as recruiting, training, writing, editing, and publishing. How does this list of functional areas look: * Recruit * Train * Gather information * Write * Edit * Publish * Steer/govern * Project manage ... what is missing? My thought from here is to: 1. Leave each process page in a master [[Category:Docs Project process]], which happens after wikibot runs from our docsproject.psv choices. 2. Add each process page to one or more sub-categories, for example [[Category:Docs Project recruiting process]]. The pattern of "Docs Project something process" is pretty clean and clear. This avoids obscuring acronyms, e.g. SOP for 'standard operating procedure'. We'll want a master page for each functional area, and it links to each of the other pages used in that process that also happen to be in the same sub-category. The sub-category page is a nice way to see all pages in a process. This is my thinking so far in how to improve our processes, clean-up the content, and use a MediaWiki-smart approach. - Karsten -- Karsten 'quaid' Wade, Community Gardener http://quaid.fedorapeople.org AD0E0C41

1 0

process docs overview
by Karsten Wade 01 Jan '09

01 Jan '09

In doing all the page renaming setup, I included a number of pages in Category:Docs_Project_process. The end result is (currently) 28 pages that contain various parts of our process. My next thought with this list is to organize it a bit in to different types of process, look for redundant content, and see about organizing a single page (Docs_Project_workflow?) as having links out to each of the process pages. Take a look at these various process pages and see if you see: * Anything missing? ** Anything needs to go away? * Good ideas on organizing * Categories these could be further sub-divided in to Cheers - Karsten DocsProject/FixingBugs|Handling_documentation_bugs|Docs_Project,Docs_Project_process DocsProject/HighlightedForDocs|How_to_submit_content_to_the_Docs_Project|Docs_Project,Docs_Project_process DocsProject/HowToReview|How_to_review_documentation|Docs_Project_process DocsProject/Join|Joining_the_Docs_Project|Docs_Project,Docs_Project_process DocsProject/Join/CheckList|Joining_the_Docs_Project_checklist|Docs_Project,Docs_Project_process DocsProject/PackageBuild|Building_packages_for_Docs_Project|Documentation_Guide,Docs_Project_process DocsProject/PackagePrep|Preparing_packages_for_Docs_Project|Documentation_Guide,Docs_Project_process DocsProject/Policy/FDSCoElections|Docs_Project_Steering_Committee_elections_process|Docs_Project_process DocsProject/ReleaseNotes/Process|Release_notes_process|Docs_Project_process DocsProject/ReleaseNotes/TrackingPage|Release_notes_bug_trackers|Docs_Project_process DocsProject/SOP/Release|Docs_Project_release_SOP|Docs_Project_process DocsProject/Schedule|Docs_Project_schedule|Docs_Project,Docs_Project_process DocsProject/SteeringCommittee/ProcessDocs|Docs_Project_Steering_Committee_process|Docs_Project_process DocsProject/StyleGuide|Docs_Project_Style_Guide|Docs_Project_process,Documentation DocsProject/StyleGuide/CommonMistakes|Docs_Project_Style_Guide_-_Common_Mistakes|Docs_Project_process,Documentation DocsProject/StyleGuide/ContentAndRendering|Docs_Project_Style_Guide_-_Content_and_Rendering|Docs_Project_process,Documentation DocsProject/StyleGuide/DatesAndTimes|Docs_Project_Style_Guide_-_Dates_and_Times|Docs_Project_process,Documentation DocsProject/StyleGuide/FedoraSpecific|Docs_Project_Style_Guide_-_Fedora_Specific|Docs_Project_process,Documentation DocsProject/StyleGuide/GeneralGuidelines|Docs_Project_Style_Guide_-_General_Guidelines|Docs_Project_process,Documentation DocsProject/StyleGuide/IntroductionToStyle|Docs_Project_Style_Guide_-_Introduction_to_Style|Docs_Project_process,Documentation DocsProject/StyleGuide/QuickReference|Docs_Project_Style_Guide_-_Quick_Reference|Docs_Project_process,Documentation DocsProject/StyleGuide/Resources|Docs_Project_Style_Guide_-_Resources|Docs_Project_process,Documentation DocsProject/TrackingPage|Docs_Project_tracking_page|Docs_Project_process DocsProject/Translation|Translating_documentation|Docs_Project,Docs_Project_process DocsProject/WhatToDocument|What_to_document_for_Fedora|Docs_Project,Docs_Project_process DocsProject/Wiki2XML|Converting_wiki_to_DocBook_XML|Docs_Project_process DocsProject/Wiki2XML/ReleaseNotes|Release_notes_wiki_to_XML_conversion_process|Docs_Project_process DocsProject/WorkFlowIdeas|Improving_the_Docs_Project_workflow|Docs_Project_process,Improving_the_Docs_Project_workflow -- Karsten 'quaid' Wade, Community Gardener http://quaid.fedorapeople.org AD0E0C41

1 0

RFC: Docs Project page renaming
by Karsten Wade 31 Dec '08

31 Dec '08

Attached is the finished version of the file that directs 'wikibot' in renaming and relinking the pages under wiki/DocsProject. The file also shows which categories the pages need to be included in, one or more categories per page. The format is: #Format: OldName|New_Name|Category,Category Two I opted to use '_' for all space instances to remove ambiguity. I also used 'Archive:' for the new name if the page is to be archived. The archiving step should just append 'Archive:' to the front of the old name, e.g.: DocProject/Foo/Page/Nested/So/Deep|Archive:|Docs_Project_archives .. should rename the page to 'Archive:DocProject/Foo/Page/Nested/So/Deep' and put it in the Category:Docs_Project_archives. I generally like the names I chose, and we can always rename later. If you have any better suggestions, make them here so we can discuss. Let's just be careful to not overly plan the bikeshed color, eh? - Karsten -- Karsten 'quaid' Wade, Community Gardener http://quaid.fedorapeople.org AD0E0C41

1 0

2025

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

2004

2003

2002

docs January 2009