Matthew, Betty, et al
What is the status of the user's guide? I wanted to help more but I haven't gotten a FC9 box put together to run through fact checking for you. :(
I would like to contribute to the FC10 version though - specifically I would like to expand on Managing Photos to include some screen shots and reference some other included software and options.
Will that be done in the wiki? Or straight in XML from a git repo? I'm good with either - just let me know where the FC10 version is located as soon as you get it moved over.
-Susan
As of Friday, I have converted the available pieces of the Users Guide to Docbook XML. I don't know where to upload the files so I still have them. I created a PDF of the users guide and sent a copy out to the group on Friday (or Saturday).
When other pieces are completed I will convert those as well. The conversion process is pretty smooth now - only occasional minor tweaks.
I used the standard Docbook XSLT's to create the PDF - it would probably be worthwhile to run the file through Publican (I don't know where a copy of that stylesheet resides).
Betty
<quote who="susan_lists@ties.org">
Matthew, Betty, et al
What is the status of the user's guide? I wanted to help more but I haven't gotten a FC9 box put together to run through fact checking for you. :(
I would like to contribute to the FC10 version though - specifically I would like to expand on Managing Photos to include some screen shots and reference some other included software and options.
Will that be done in the wiki? Or straight in XML from a git repo? I'm good with either - just let me know where the FC10 version is located as soon as you get it moved over.
-Susan
-- Susan Lauber, (RHCX, RHCA, RHCSS) Lauber System Solutions, Inc. http://www.laubersolutions.com gpg: 15AC F794 A3D9 64D1 D9CE 4C26 EFC3 11C2 BFA1 0974 -- fedora-docs-list mailing list fedora-docs-list@redhat.com To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
/////////////////////////////////// Betty Harvey | Phone: 410-787-9200 FAX: 9830 Electronic Commerce Connection, Inc. | harvey@eccnet.com | Washington,DC SGML/XML Users Grp URL: http://www.eccnet.com | http://www.eccnet.com/xmlug/ ////////////////////////////////\//
On Tue, Jan 06, 2009 at 12:44:41PM -0500, Betty Harvey wrote:
As of Friday, I have converted the available pieces of the Users Guide to Docbook XML. I don't know where to upload the files so I still have them.
In coordination with the rest of the User Guide team, you want to upload them to the git repository.
To start, install git:
sudo yum install git
Then, clone the repository:
git clone ssh://<username>@git.fedorahosted.org/git/docs/userguide.git
The repository is entirely blank, save for an initiating file (I think.)
From there you want to install Publican, create a blank book, put that in the repository, and then start adding your XML files.
cd userguide/ sudo yum install publican ... create_book --name=User_Guide --brand=fedora --lang=en-US --type=Book cp /path/to/converted/*.xml User_Guide/en-US/
Using Publican is covered in the Publican guide:
https://fedorahosted.org/publican
Using git, there are a number of good tutorials. You can start here:
https://fedoraproject.org/wiki/Git_Quickref http://book.git-scm.com/index.html
I created a PDF of the users guide and sent a copy out to the group on Friday (or Saturday).
When other pieces are completed I will convert those as well. The conversion process is pretty smooth now - only occasional minor tweaks.
Similarly to the XML, we want to get working code, configurations, and usage READMEs in to the 'fedora-doc-utils' repository:
https://fedorahosted.org/fedora-doc-utils/
That way other people can do the conversions, etc.
I used the standard Docbook XSLT's to create the PDF - it would probably be worthwhile to run the file through Publican (I don't know where a copy of that stylesheet resides).
rpm -ql publican|grep xsl /usr/share/publican/xsl /usr/share/publican/xsl/CatalogManager.properties /usr/share/publican/xsl/changelog.xsl /usr/share/publican/xsl/defaults.xsl /usr/share/publican/xsl/docbook.dtd.xml /usr/share/publican/xsl/dt_htmlsingle_spec.xsl /usr/share/publican/xsl/dt_xml_spec.xsl /usr/share/publican/xsl/eclipse.xsl /usr/share/publican/xsl/html-single.xsl /usr/share/publican/xsl/html.xsl /usr/share/publican/xsl/htmlhelp.xsl /usr/share/publican/xsl/omf.xsl /usr/share/publican/xsl/pdf.xsl /usr/share/publican/xsl/saxon65.jar /usr/share/publican/xsl/sub_package_htmlsingle.xsl /usr/share/publican/xsl/sub_package_xml.xsl /usr/share/publican/xsl/subtitle.xsl /usr/share/publican/xsl/txt.xsl /usr/share/publican/xsl/web-spec.xsl /usr/share/publican/xsl/xhtml-common.xsl
- Karsten
On Tue, Jan 06, 2009 at 12:36:15PM -0500, susan_lists@ties.org wrote:
Matthew, Betty, et al
What is the status of the user's guide? I wanted to help more but I haven't gotten a FC9 box put together to run through fact checking for you. :(
We're nearly there with the F9, so it might be fine to go ahead with F10 for you?
Or a virtualized instance might help.
I would like to contribute to the FC10 version though - specifically I would like to expand on Managing Photos to include some screen shots and reference some other included software and options.
That sounds good, although I'll give you the usual caveat about screenshots and why we eschew them:
https://fedoraproject.org/wiki/DocsProject/StyleGuide/FedoraSpecific#Screens...
Will that be done in the wiki? Or straight in XML from a git repo? I'm good with either - just let me know where the FC10 version is located as soon as you get it moved over.
That is a good question that Matthew and others need to think about. Once the initial F9 User Guide is converted, it might be easier to do the F10 update directly in XML.
However, history around here has shown that you get a *lot* more contributors when you draft in the wiki. If the conversion process can be brought down to a few hours or so, then doing the work in the wiki makes more sense -- you get more collaboration, more visibility in to the work in progress, and so forth.
- Karsten
On Tue, Jan 6, 2009 at 1:34 PM, Karsten Wade kwade@redhat.com wrote:
On Tue, Jan 06, 2009 at 12:36:15PM -0500, susan_lists@ties.org wrote:
Matthew, Betty, et al
What is the status of the user's guide? I wanted to help more but I haven't gotten a FC9 box put together to run through fact checking for you. :(
We're nearly there with the F9, so it might be fine to go ahead with F10 for you?
Or a virtualized instance might help.
Hmm... if I had more memory in that old laptop I've been using. :) And I found my livecd but only helps with gnome which is mostly done.
I would like to contribute to the FC10 version though - specifically I
would
like to expand on Managing Photos to include some screen shots and reference some other included software
and
options.
That sounds good, although I'll give you the usual caveat about screenshots and why we eschew them:
https://fedoraproject.org/wiki/DocsProject/StyleGuide/FedoraSpecific#Screens...
Fair enough. A number of other sections should be trimmed of some of the screenshots too then. That is something else I can help with in moving to FC10 - update or remove screenshots in users guide. [laubersm makes note, welcomes nudges if she forgets]
I do know a lot of users that need encouragement to install and try something and a screen shot or two often catches their interests. I will look into adding a reference to the upstream project's screenshots to address this need. The only problem with that is back to version mismatches.
Also in the middle of a lot of steps screenshots help a new user check that they got to the correct place. I agree that they are NOT needed for every step and they are often used too much.
Will that be done in the wiki? Or straight in XML from a git repo? I'm good with either - just let me know where the FC10 version is located
as
soon as you get it moved over.
That is a good question that Matthew and others need to think about. Once the initial F9 User Guide is converted, it might be easier to do the F10 update directly in XML.
However, history around here has shown that you get a *lot* more contributors when you draft in the wiki. If the conversion process can be brought down to a few hours or so, then doing the work in the wiki makes more sense -- you get more collaboration, more visibility in to the work in progress, and so forth.
+1
I saw a user guide git location http://git.fedoraproject.org/git/?p=docs/user-guide.git;a=summary Is this where the XML should go? I'm new to git - does it get branched under here for FC9 or should it be named FC9 and a new one for FC10 in parallel? Where did the FC8 stuff end up? [laubersm knows she has not been paying attention to all the locations]
-Susan
- Karsten
-- Karsten 'quaid' Wade, Community Gardener http://quaid.fedorapeople.org AD0E0C41
Sorry I haven't jumped in on this email sooner; I've been moving back into Clemson today and haven't been near a computer.
Will that be done in the wiki? Or straight in XML from a git repo? I'm good with either - just let me know where the FC10 version is located as soon as you get it moved over.
That is a good question that Matthew and others need to think about. Once the initial F9 User Guide is converted, it might be easier to do the F10 update directly in XML.
I say +1 on straight to XML. Despite the fact that it will have a slightly larger learning curve than editing on the wiki, I would love to get rid of the conversion process and make sure everything is nice right on the XML document. I think that'll be much cleaner in general, especially since everyone will have to be looking at the final document (as opposed to everyone writing on the wiki and then a specialized conversion team generating the final copy). I'll have to learn just as much (and probably more) than a lot of us to do it this way, but I think it's worth it. Plus, it could get newer team members familiar with git and XML so they can help on other docs.
-- Matthew
<quote who="Matthew Daniels">
I say +1 on straight to XML. Despite the fact that it will have a slightly larger learning curve than editing on the wiki, I would love to get rid of the conversion process and make sure everything is nice right on the XML document. I think that'll be much cleaner in general, especially since everyone will have to be looking at the final document (as opposed to everyone writing on the wiki and then a specialized conversion team generating the final copy). I'll have to learn just as much (and probably more) than a lot of us to do it this way, but I think it's worth it. Plus, it could get newer team members familiar with git and XML so they can help on other docs.
I agree with going to straight XML. One of the "gotcha's" that I found with extracting the data from the WIKI is that it does not extract warnings, cautions and notes. As such it required manual intervention.
I am not sure if anyone is willing to move away from the WIKI but Drupal has a module that allows native XML and rendering via a stylesheet. I am using it with a modified version of Docbook and XSLT. It works great.
Betty
-- Matthew
-- fedora-docs-list mailing list fedora-docs-list@redhat.com To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
/////////////////////////////////// Betty Harvey | Phone: 410-787-9200 FAX: 9830 Electronic Commerce Connection, Inc. | harvey@eccnet.com | Washington,DC SGML/XML Users Grp URL: http://www.eccnet.com | http://www.eccnet.com/xmlug/ ////////////////////////////////\//
I agree with going to straight XML. One of the "gotcha's" that I found with extracting the data from the WIKI is that it does not extract warnings, cautions and notes. As such it required manual intervention.
I am not sure if anyone is willing to move away from the WIKI but Drupal has a module that allows native XML and rendering via a stylesheet. I am using it with a modified version of Docbook and XSLT. It works great.
Betty
Weren't we looking at moving to a new CMS anyway? That definitely sounds like something to look into.
- Matthew
On Tue, Jan 6, 2009 at 2:47 PM, Matthew Daniels danielsmw@gmail.com wrote:
I agree with going to straight XML. One of the "gotcha's" that I found
with extracting the data from the WIKI is that it does not extract warnings, cautions and notes. As such it required manual intervention.
I am not sure if anyone is willing to move away from the WIKI but Drupal has a module that allows native XML and rendering via a stylesheet. I am using it with a modified version of Docbook and XSLT. It works great.
Betty
Weren't we looking at moving to a new CMS anyway? That definitely sounds like something to look into.
Hopefully the CMS solution can allow a compromise.
I can work with straight XML and for most docs that is a good plan.
I think that for a UG though, we can get a lot more feedback if it stays in a wiki. Remember that the people using the UG are less likely to be experienced or even interested in CLI but many already know how to edit in a wiki. We need the people who use the document to be willing to fix the document. Even if they never contribute to other documents.
Once we get to Install guides, deployment guides, security guides and other such stuff, then submitting bugs and editing xml are more reasonable expectations.
- Matthew
-- fedora-docs-list mailing list fedora-docs-list@redhat.com To unsubscribe:https://www.redhat.com/mailman/listinfo/fedora-docs-list
On Jan 6, 2009, at 3:05 PM, susan_lists@ties.org wrote:
Hopefully the CMS solution can allow a compromise. I can work with straight XML and for most docs that is a good plan.
I think the CMS would work out very well. As for staying with/leaving the wiki, I'm kinda in the middle, but I'm still leaning towards leaving it. You make some good points, but I'm not sure if the small advantages we get can weigh up against the advantages of editing right in XML.
I think that for a UG though, we can get a lot more feedback if it stays in a wiki. Remember that the people using the UG are less likely to be experienced or even interested in CLI but many already know how to edit in a wiki. We need the people who use the document to be willing to fix the document. Even if they never contribute to other documents.
The issue here is that the UG is (as it stands, at least) geared toward new users who really haven't used Linux much if at all before. They probably - with some exceptions - aren't members of the open source community, and probably don't have an FAS account. And without an FAS account, you can't edit the wiki. =)
Although we've been running this in a wiki, I don't think we've actually ever made it work like the traditional wiki. We don't really point new Fedora users to https://fedoraproject.org/wiki/User_Guide, because that's usually where we work on it; we publish it to XML. I'm fairly confident when I say that virtually nobody except us edits the User Guide, with exceptions few and far between.
- Matthew
On Tue, Jan 06, 2009 at 03:19:46PM -0500, Matthew Daniels wrote:
Although we've been running this in a wiki, I don't think we've actually ever made it work like the traditional wiki. We don't really point new Fedora users to https://fedoraproject.org/wiki/User_Guide, because that's usually where we work on it; we publish it to XML. I'm fairly confident when I say that virtually nobody except us edits the User Guide, with exceptions few and far between.
You can also tell people who want to contribute but refuse to learn XML to do the work in the wiki, then do a conversion of just that content/chapter. They can do the work in their User:Username space, for example, or directly in User_Guide.
The wiki is a content gateway drug, it gets people hooked, then we introduce them to the hard stuff.
It's more of a nightmare for the lead writer, but you can try it for a release and see if it's worth the hassle for the extra collaboration opportunities.
- Karsten
I am not sure if anyone is willing to move away from the WIKI but Drupal has a module that allows native XML and rendering via a stylesheet. I am using it with a modified version of Docbook and XSLT. It works great.
Betty
I don't mean to hijack this thread - but we'd really be interested in talking with you about Drupal as a CMS in general and the DocBook module specifically. Any chance you are coming to FUDcon? (If transportation is an issue we can probably take care of that if you are relatively close to I-95 - there is the East Coast Road Trip that has a spot open. (despite what the wiki says) http://fedoraproject.org/wiki/FUDCon/FUDConF11#East_Coast_Road_Trip_--_CONFI...
On Tue, Jan 06, 2009 at 03:04:07PM -0500, David Nalley wrote:
I am not sure if anyone is willing to move away from the WIKI but Drupal has a module that allows native XML and rendering via a stylesheet. I am using it with a modified version of Docbook and XSLT. It works great.
Betty
I don't mean to hijack this thread - but we'd really be interested in talking with you about Drupal as a CMS in general and the DocBook module specifically. Any chance you are coming to FUDcon? (If transportation is an issue we can probably take care of that if you are relatively close to I-95 - there is the East Coast Road Trip that has a spot open. (despite what the wiki says) http://fedoraproject.org/wiki/FUDCon/FUDConF11#East_Coast_Road_Trip_--_CONFI...
I haven't spelled out any CMS plans for FUDCon this weekend, but we are going to try to get some stuff done during the hackfest.
Drupal is clearly on a short-list for us, for any number of reasons, such as the rich extensions library. I wasn't aware of that one, it is encouraging to hear Betty's enthusiasm for it.
- Karsten
<quote who="David Nalley">
I am not sure if anyone is willing to move away from the WIKI but Drupal has a module that allows native XML and rendering via a stylesheet. I am using it with a modified version of Docbook and XSLT. It works great.
Betty
I don't mean to hijack this thread - but we'd really be interested in talking with you about Drupal as a CMS in general and the DocBook module specifically. Any chance you are coming to FUDcon? (If transportation is an issue we can probably take care of that if you are relatively close to I-95 - there is the East Coast Road Trip that has a spot open. (despite what the wiki says) http://fedoraproject.org/wiki/FUDCon/FUDConF11#East_Coast_Road_Trip_--_CONFI...
Humm - I hadn't thought about coming to FUDcon but I could possibly drive up. I am on the I 95 corridor between Washington and Baltimore but I am on-site on Friday so couldn't leave until the evening. If I can find babysitting for the boys (dogs) I will try to make it.
Betty
/////////////////////////////////// Betty Harvey | Phone: 410-787-9200 FAX: 9830 Electronic Commerce Connection, Inc. | harvey@eccnet.com | Washington,DC SGML/XML Users Grp URL: http://www.eccnet.com | http://www.eccnet.com/xmlug/ ////////////////////////////////\//
docs@lists.stg.fedoraproject.org