User Guide status?

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

[Betty Harvey]

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=&quot;susan_lists(a)ties.org&quot;&gt;
>  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(a)redhat.com
>  To unsubscribe:
>  https://www.redhat.com/mailman/listinfo/fedora-docs-list 

/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
Betty Harvey                         | Phone: [phone] FAX: 9830
Electronic Commerce Connection, Inc. |
harvey(a)eccnet.com                    | Washington,DC SGML/XML Users Grp
URL:  http://www.eccnet.com          | http://www.eccnet.com/xmlug/
/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\\/\/

[Karsten Wade]

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
-- 
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41

[Karsten Wade]

On Tue, Jan 06, 2009 at 12:36:15PM -0500, susan_lists(a)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#Scre...

>  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
-- 
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41

On Tue, Jan 6, 2009 at 1:34 PM, Karsten Wade <kwade(a)redhat.com&gt; wrote:

>  On Tue, Jan 06, 2009 at 12:36:15PM -0500, susan_lists(a)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#Scre...
>  
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
>
>  
-- 
Susan Lauber, (RHCX, RHCA, RHCSS)
Lauber System Solutions, Inc.
http://www.laubersolutions.com
gpg: 15AC F794 A3D9 64D1 D9CE  4C26 EFC3 11C2 BFA1 0974

[Matthew Daniels]

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

[Betty Harvey]

<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(a)redhat.com
>  To unsubscribe:
>  https://www.redhat.com/mailman/listinfo/fedora-docs-list
>  

/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
Betty Harvey                         | Phone: [phone] FAX: 9830
Electronic Commerce Connection, Inc. |
harvey(a)eccnet.com                    | Washington,DC SGML/XML Users Grp
URL:  http://www.eccnet.com          | http://www.eccnet.com/xmlug/
/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\\/\/

[Matthew Daniels]

>  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(a)gmail.com&gt; 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(a)redhat.com
>  To unsubscribe:https://www.redhat.com/mailman/listinfo/fedora-docs-list
>  


-- 
Susan Lauber, (RHCX, RHCA, RHCSS)
Lauber System Solutions, Inc.
http://www.laubersolutions.com
gpg: 15AC F794 A3D9 64D1 D9CE  4C26 EFC3 11C2 BFA1 0974

[Matthew Daniels]

On Jan 6, 2009, at 3:05 PM, susan_lists(a)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

[Karsten Wade]

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
-- 
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41

[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_--_CO...

[Karsten Wade]

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_--_CO...
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
-- 
Karsten 'quaid' Wade, Community Gardener
http://quaid.fedorapeople.org
AD0E0C41

[Betty Harvey]

<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_--_CO...
>  
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: [phone] FAX: 9830
Electronic Commerce Connection, Inc. |
harvey(a)eccnet.com                    | Washington,DC SGML/XML Users Grp
URL:  http://www.eccnet.com          | http://www.eccnet.com/xmlug/
/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\\/\/