gmane.linux.redhat.fedora.documentation

Footnoteable Wiki

Nigel Jones — 2008-10-07T02:22:36

Hi Everyone, The Fedora Orbital Laser[1] has cooled down enough to allow us to work on getting Footnotes[2] in the wiki[3]. There is some excellent documentation[4] on the Mediawiki website on how to use them if you have not in the past. Thank you for bearing through this announcement[5], Nigel Jones[6] --References-- [1] http://www.mail-archive.com/fedora-announce-list< at >redhat.com/msg01140.html [2] Not to be mistaken with 'Foodnotes' [3] http://fedoraproject.org/wiki/ [4] http://www.mediawiki.org/wiki/Extension:Cite/Cite.php#Usage [5] I use too many footnotes eh?

Self-Introduction: A. Mani

Mani A — 2008-10-07T00:19:29

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hello All, My name is A. Mani. I am a Mathematician and a logician. My research interests are in Algebra, Partial Algebra, Logic, Rough Sets and Foundations of Mathematics. I am good in specifications, formal specifications, R, Prolog, Scheme, LaTeX and scientific computing too. This has led to a few part-time projects during the last few years. I have been involved in FLOSS and OSS promotion for over six years and see a very bright future for the Fedora project. I coordinate the activities of ILUG-CALINFO (www.ilug-cal.info) and am active at LQ too. I would like to improve existing documentation and contribute to specialized sections. My wiki page is at https://fedoraproject.org/wiki/User:amani My homepage is at http://amani.topcities.com I am a Fedora Ambassador too. Best A. Mani - -- A. Mani Member, Cal. Math. Soc -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) Comment: http://getfiregpg.org iD8DBQFI6quRoIK4BlImohYRArtNAKCX2lLNfVOKra4ndTNZpUcxsBQQQQCfZpQ8 TLc86bdxV2c6NWqGgJ7ZzYc= =7zQn -----END PGP SIGNATURE-----

publishing documentation in Fedora

Murray McAllister — 2008-10-05T23:36:18

Hi, Two questions: 1. Is there any documentation on the procedure for having documentation published in Fedora, for example, hosted on ? 2. To get documentation in there, do I have to use the fedora-docs toolchain to make the RPMs? Cheers.

Outage Notification - 2008-10-05 07:00 UTC

Mike McGrath — 2008-10-03T14:56:47

There will be an outage starting at 2008-10-05 07:00 UTC, which will last approximately 2 hours. To convert UTC to your local time, take a look at http://fedoraproject.org/wiki/Infrastructure/UTCHowto or run: date -d '2008-10-05 07:00 UTC' Affected Services: Buildsystem CVS / Source Control Database DNS Fedora Hosted Fedora People Fedora Talk Mail Mirror System Torrent Websites Unaffected Services: All Ticket Link: https://fedorahosted.org/fedora-infrastructure/ticket/875 Reason for Outage: Doing our monthly updates to our systems, there's a kernel update this time around and we'll be rebooting everything. In theory most systems won't go down at all. But many will be down for a few minutes at a time during our 2 hour outage window. Contact Information: Please join #fedora-admin in irc.freenode.net or respond to this email to track the status of this outage.

F10 Schedule Revised

John Poelstra — 2008-10-03T14:32:43

I have published updated schedules based on the great gobby editing sessions we had this week with the Documentation and Translation teams. Note each schedule only shows the tasks for that specific team... we can adjust this if that is confusing: http://poelstra.fedorapeople.org/schedules/f-10/f-10-docs-tasks.html http://poelstra.fedorapeople.org/schedules/f-10/f-10-trans-tasks.html For a view of all combined tasks for all teams: http://poelstra.fedorapeople.org/schedules/f-10/f-10-all-tasks.html As I mentioned during the Documentation session, I hope this process isn't too frustrating. I think it will take a few iterations to make sure we are all using and understanding the same terminology. There is probably still some work to be done around the 0-day tasks as someone pointed out on the translation list. So next I'm proposing that both Documentation and Translation meet on gobby and if possible fedora talk (for audio conversation) next week to work out the remaining points of difference and confusion :) Thanks again for your patience and I hope this process is helpful. John

A New Look at How We Write Content for the Desktop User Guide

Elizabeth Ann West — 2008-10-03T14:09:17

Hello All, I am a fairly new contributor to Fedora-Docs, and a <1 year Linux user. My background is predominantly writing, so I approach the documentation more from a literary stand point than a heavily entrenched computer user. If anything, I'm a good example of the type of person you are looking to convert from proprietary software to open source. I took a hard look at the Desktop Users Guide F9, specifically the page giving instructions to install financial software. First, there was a large issue with the content-- the instructions simply would not work for a new user with Fedora 9. Second, the instructions were not clear for a brand new user to Linux. After finishing the content change, and major style changes to the Financial Software page, I deconstructed the changes and differences so others may learn from them, and contribute their own ideas and experiences. Yes, we are writing documentation for free, but we have an opportunity here as open source enthusiasts to use our piece of the project at large to further the cause and acceptance of Fedora as an operating system. These suggestions below are only for the Desktop Users Guide, the specialized guide for new users of Fedora, presumably coming from Windows, without Linux experience. For discussion purposes, this is the old page: https://fedoraproject.org/wiki/Docs/Drafts/DesktopUserGuide/Financial This is the new and improved page: https://fedoraproject.org/wiki/User_Guide-Financial_Software Here are the major improvements I want to point out as potential "best practices" for future work on the Desktop User Guide: * The page stands completely alone for a new user. Links and everything are great, but switching to a new operating system is highly nerve-wracking. I have done this 3 times in the last 5 months, including my first switch to Linux from Windows. Experienced Linux users take so much for granted, when just something as simple as installing software from a command line is foreign (a distant memory for Windows users who remember DOS). Ease new users' frustrations by providing all needed instructions in one document page or chapter that apply to functionality, or getting something done. Certainly link to topics that may be of interest to me for other actions, but don't leave out information I need to accomplish what I want/need to do right now. It's like giving landmarks when you give someone directions for the first time, instead of letting them rely just on Mapquest, or sending them an entire road map for the state. * Stand alone chapters fit in more with how all users utilize help manuals. We're all guilty of this one. No one voluntarily reads a help manual from cover to cover unless he or she absolutely must. New and old users alike use an index for printed manuals to jump right to the information needed, and electronically search is a godsend. Working to write and offer stand alone chapters helps the users help themselves in the manner they naturally will try first. The fewer places a user must go for information, the more likely he or she can use the data effectively. * White space is visually pleasing in print and electronically. The old version crams together two sets of instructions to perform the same task, without clearly delineating when the desired result is accomplished in either situation. The new version sets off the simple sentence "[Application] is now installed on your computer." with a double line space on each side. This naturally draws the eye to the completion of the first set of instructions, without a garish ALL CAPS or other formatting scream. Breaking up complex instruction sets with this practice re-focuses the reader's attention. This is vital, as it is likely the user is hopping between windows, reading directions, and then carrying them out. Under the old instruction set, a new user from Windows very possibly could install with the command line, miss the concept that terminal and Pirut are two different methods of the same thing (after all both are new to the user), and keep following the directions ticking that box to remove the application. Over and over again until they decide it's just broken. The new page lets the reader know in the introduction two installation methods are available, and then uses white space to reinforce the distinction. * Give Graphical User Interface(GUI) example before command line, if possible. The Desktop User Guide has an audience of someone with no previous Linux experience. So, start with what is familiar, and move to the unfamiliar. The prevalence of Windows has made mainstream computer users clickers, clickers, clickers. Even shortcut commands are forsaken in the culture of right-clicking. Windows has trained people to click 'Next', a seemingly infinite numbers of times, and follow baby steps. It will naturally occur to the new users how powerful and efficient the command line is to Linux. Eventually, they will get to where they want to do something beyond the scope of the Desktop User Guide and it will only have instructions for the command line in a forum post or other documentation. Starting out, it's enough for them to know it exists and it will accomplish the same tasks as that clicking. Now, if the topic is on the command line commands, there is little reason to start with GUI. * Qualify the information the user is reading. One of the largest differences between Windows and Linux a new user immediately encounters is just the sheer increase in information his or her computer is sharing. On top of the increase, the computer also demands new decisions the user never had to make before. What do you mean I have the option of NOT installing these other packages, the ones you are telling me will make this package I do want work? People are naturally intimidated by notations they do not understand, like the numbers with decimal points under a package's name in Add/Remove Software. With instructions, leaving out actions or messages the computer will give confuses a new user. It starts questions that stop the process of learning: Is this normal? Where is this in the instructions? Why can't I find this step? Did I mess up? Going back to the landmarks concept when you give someone road directions, I added the messages Add/Remove Software gives while it is performing the user's requests. This is from my personal first experiences with Add/Remove Software, it was s......l......o......w (I fixed it when I disabled the auto-updater, not advice I want to share as a good habit to get into). Everything else, Internet, chat, was moving very briskly. As soon as I quit everything and just started Add/Remove Software it was still so painfully slow even I gave up a few times trying to install GnuCash. If I was reading instructions, the "Downloading repository information" landmark would at least reassure me the application was still working, not stuck or refreshing itself. Some other quick notes: * Changed icon info to "associated" as neither installation method auto-creates desktop launcher. Didn't get into that because it doesn't fit the "do I need it for this function" litmus test. * Clarified confusion the first page had of Live-CD versus DVD to plainly state DVD has both, does not install automagically, if you do not have Internet access use the DVD, otherwise..... list of instructions to install. * Qualified the information that suddenly appears in the bottom boxes when they tick the box as just extra information so they don't think it affects the install. * Included [y/N] step for command line so the new user isn't hesitant about answering yes. Anytime a Windows user encounters typing 'y' or 'n' it's not usually a good thing. Also, again qualified all that test the Terminal spits out is just information about the application so they don't try to keep up. * Opted to teach Search box rather than clicking Office category because Office category takes too long to populate, and new users will be turned off trying to find the exact name of the package to install from that long list when none of the icons are different. Limitations/Criticisms * Have not placed in links to those "extra words and concepts" like KDE Desktop Environment should link to the page about that. I don't quite understand yet which are new versus old, versus frozen in the document structure (many all look the same to me). I need help to add that in. * Have not taken my editor's scalpel to the wording. I know there are a number of passive sentences, but I am too close to the text right now to see the problems or areas for improvement. In a few days, I can better judge nuances in wording. * Other writers may not care for this style as it is more involved, and fights against the elitist concept of self discovery that is so common in the open source community. * Other writers and Fedora doc leaders may not care for the writing style because of the departure from the traditional, or view it as repeating the same information over and over again. * Many others I'm sure..... I invite others to weigh in on this issue. I am very open to hear criticism and realize critiquing my content is not the same as critiquing me. :) I want to offer my strong English background to help our group as a whole start to question when we work on documents: Who am I writing this for? What knowledge will they already know? Always Smiling, Elizabeth Ann West

Wiki-to-XML for F10

Karsten 'quaid' Wade — 2008-10-03T00:42:56

working on scheduling via gobby 2300 UTC 1 Oct (right now)

Karsten 'quaid' Wade — 2008-10-01T22:58:10

prompts in command examples

Murray McAllister — 2008-10-01T22:17:06

Hi, The Red Hat documentation team recently had a discussion about using prompts (such as "$" and "#") in command examples. Joshua "top-posting ftw" Wulf came up with the following, and everyone agreed (I think...): --- OK, here it is: When it's a command that should (could) be cut and pasted, it should have no prompt. Example: ls -Z /tmp When it's a record of an interactive session then the prompt should be included to distinguish commands from output. Example: # ls -Z /tmp -rw-rw-r-- auser auser user_u:object_r:user_home_t bar -rw-rw-r-- auser auser user_u:object_r:user_home_t foo And when you want to make some commentary on that, you close the box and then speak. --- Does anyone have any suggestions or objections? Cheers.

Self-Introduction:

Kam Salisbury — 2008-09-28T23:36:51

Hi, I'm Kam Salisbury. I live and work in Philadelphia Pennsylvania USA. Several small articles and tips regarding using Linux to get real world tasks accomplished. Some items are more suitable for other system administrators or hobbiests. Over ten years experience supporting and using computer technology in Windows, Novell and Linux environments. design, other so-called soft skills (people skills), programming, etc. No published programs to claim fame to but definetly scripting capable - shell, HTML/CSS, PHP, Java. As a network manager I am comfortable speaking in front of groups. I want to help. Kam Salisbury kam< at >kamsalisbury.com FAF1751E fingerprint = DC3A 73C0 199D 0C29 BDCD 9D2A 8014 9957 FAF1 751E

Release Notes file renaming

Paul W. Frields — 2008-09-27T21:07:52

structure for F10 final release notes

Karsten 'quaid' Wade — 2008-09-26T01:11:35

[Fwd: Re: Fedora 10's official Default theme]

Paul W. Frields — 2008-09-25T18:51:07

Request for Review: DiskEncryptionUserGuide

Dave Lehman — 2008-09-25T17:28:31

Hi all, My name is Dave Lehman. I am one of the engineers that works on anaconda (the Fedora installer). I've written a draft of a document intended to document the use of dm-crypt/LUKS encrypted block devices. Since F9 we have supported the creation and use of block devices encrypted using dm-crypt/LUKS in the anaconda installer. This document aims to give some basic information about disk encryption in general, as well as the LUKS technology, and then go on to detail the creation and configuration of such devices. My hope/intention is that this document, whether integrated into another existing document or not, can be published at such a time as to accompany the general availability of F10. Here is a link to the draft document: https://fedoraproject.org/wiki/Docs/Drafts/DiskEncryptionUserGuide I am by no means a writer, technical or otherwise, so I will need all the help I can get. Thanks in advance, Dave

Now where did I put those release notes?

Jason — 2008-09-25T03:17:26

mtg today 1900 UTC - slip, flip, or skip

Karsten 'quaid' Wade — 2008-09-24T16:21:02

Doc schedule changes for slip

Karsten 'quaid' Wade — 2008-09-23T19:02:05

Ian Weller — 2008-09-21T20:22:25

Intro of Elizabeth Ann West

Elizabeth Ann West — 2008-09-21T02:42:03

Hello all, I am Elizabeth Ann West, a new contributor to the Fedora Documentation Project recruited by David Nalley. I am the Chief Data Collector of the Charleston, SC Linus Users Group. I met David Nalley when he represented Fedora at our Linux Demo Day last weekend. It was pretty successful as our first one, we had about 60 people show up, and we had a number of computers setup for visitors to play with hands on. I made the switch to Linux in April, using Ubuntu. I have the Fedora 9 CD and like what I saw. In the next few days I will be triple booting my computer. I have to keep XP on my laptop due to work, as it is the only machine in the house with Windows. I am a professional web content writer by trade. I am a Tech Jock at filetonic.com where I answer general and Microsoft computing questions. I try to write in a way for all to understand the more technical aspects of computing, while also empowering them to take more control over their systems. Though I hold a degree in Political Science with a minor in English Literature from Christopher Newport University in Newport News, VA, I have a strong math and science background. I broke my Dad's heart the day I told him I wasn't going to become an engineer. I will be mainly focusing on editing the documentation in existence, bringing it up to a more professional publishing standard. I would like to say if I happen to change your document, I do my best to explain every change in comments so you understand it is nothing personal. I notice the most common communication barrier in the documentation is just a lack of editing for clarity. I see many sentences with dead weight words muddling the original message of the author. I edit from a mechanical point of view. Every word in a sentence to me is a mechanical entity, linked together to make the sentence train. If a word isn't pulling its weight, it's cut. I also look for crutch words and phrases--repeated use of the same words through out a page. All of these things I do myself whenever I write a first draft, and I must force myself to go back through my own writing with my red pencil. I do want to say overall the content in the Fedora Documentation Project is impressive. I wouldn't be able to make many of the edits I have so far if the original content was not of a robust, high quality. Right now I am working on the style guide to become immersed in the overall writing style. Thank you all for having me as part of the team. Please do not hesitate to ask me any questions about specific grammar rules or writing questions. I am more than happy to help where I can, and I am thankful to finally have a way to contribute back to the open source community I have grown to adore. Always Smiling, Elizabeth Ann West Always Smiling, Elizabeth Ann West E. A. West Writing Services "The best in affordable and quality writing services." www.eawestwriting.com

Self Introduction: Matthew Daniels

Matthew Daniels — 2008-09-20T16:50:28

Hey everyone, My name is Matthew Daniels and I'm an undergraduate studying Physics and Astronomy at Clemson University, although my hometown is Charleston, SC. I've been using Linux as my primary OS for about 5 years now, and I've been using Fedora since FC6 came out in '06. I actually have done a little bit of contract programming, and my coding skills are mediocre. I'm comfortable is Perl and Java, and can, for the most part, hold my own in C and Python. But, this is probably not sufficient for making large-scale contributions to the Fedora Project. However, I regard myself a pretty good writer, and I recently realized that I actually kind of enjoy writing program documentation. So, since Fedora -- and Linux, in general -- have been so good to me, I've made it one of my personal goals as of late to start trying to give back to the OSS community. I felt that actually joining a project and getting my hands dirty would be a good way to do it. Accordingly, this is my first time contributing to a project like this. In the future, I think I may also wish to become a Fedora Ambassador and try to push Fedora with Clemson's Linux User Group, since they're sorta just stuck on Ubuntu right now. But for now, I'd like to take things one step at a time, and contribute to the fedora-docs group as much as possible. Hopefully, you guys have something I can do; even if it's just cleaning up broken links for now, that's fine. I just want to help. So... that's my self introduction! If I missed anything, or if anyone has any questions, please don't hesitate to email me. -------------------------------------------------------------------------------- pub 1024D/5C0D4723 2008-09-20 [expires: 2009-09-20] Key fingerprint = E9E5 3017 C4A6 1813 A0A9 6D49 84AD EB20 5C0D 4723 uid Matthew Daniels (danielsmw) gmail.com> sub 2048g/94106677 2008-09-20 [expires: 2009-09-20] -------------------------------------------------------------------------------- Cheers, Matthew Daniels -- _____________________________ Reply To: danielsmw< at >gmail.com

fedora docs style guide for documentation

Murray McAllister — 2008-09-20T02:13:08

Hi, If Red Hat produce documentation that is hosted on fedorahosted, does it have to follow the fedora docs style as outlined at ? Also, what is the consequence of breaking these rules, such as including screenshots :) Are there any guidelines for what tags should be used, and how to spell common terms (e.g. backup, back up, domain name, file system etc?) There are documents for these things in Red Hat, but I am not sure if they go against fedora guidelines (since I could not find them ). I found a word list at - is there anywhere else I should be looking? Thanks for your help.