Question on modifing User Guide

classic Classic list List threaded Threaded
20 messages Options
Reply | Threaded
Open this post in threaded view
|

Question on modifing User Guide

Dave Herman
Prompted by setting up simple account tree for testing and several
questions here and on the user list, I started to review
the GnuCash User Guide.  While I am not a "tech writer", I could assist
by updating some of the screen shots and adding
some examples.  I expect there are many others "readers" who could
contribute examples or just FAQs with answers.

It, the User Guide does need to be updated, which raised a couple of
what are probably very basic questions.

I am able to create an updated HTML User Guide by doing a  make in the
gnucash-doc-svn  directory,  how do I generate
the PDF files?

Are the existing screen shots reasonably stable?

Is there a list of "standard" Names - GnuCash/GNUCash/GNUcash ? GnuCash
seems to be most accepted correct ?

How should updates be feedback ?  svn -diff only resulted in errors.
Would a tarball of a chapter and associated image fies
be the preferred method?

any suggestions or recommendations?

Dave

P.S. I started on the chapter on Investments (Chapter 8).  Sales for
gains & loss seem to be an issue.









 

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Bengt Thuree

On Fr, 2006-03-24, 04:04, Dave Herman skrev:
> Prompted by setting up simple account tree for testing and several
> questions here and on the user list, I started to review
> the GnuCash User Guide.  While I am not a "tech writer", I could assist
> by updating some of the screen shots and adding
> some examples.  I expect there are many others "readers" who could
> contribute examples or just FAQs with answers.

Yes, I totally agree with you.
My time is very limited, but will try and help in whatever capacity I can.
Proof reading / comments mainly for a while. Also my knowledge of GnuCash
is very limitied, just started using it

> P.S. I started on the chapter on Investments (Chapter 8).  Sales for
> gains & loss seem to be an issue.

Yes, this is one of the areas I am mainly interested in.
(Also having problems with.)
Investments in other currencies than default needs to be covered.

/Bengt

--
Bengt Thuree   [hidden email]    www.thuree.com/bt

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Derek Atkins
In reply to this post by Dave Herman
Hi,

Quoting Dave Herman <[hidden email]>:

> Prompted by setting up simple account tree for testing and several
> questions here and on the user list, I started to review
> the GnuCash User Guide.  While I am not a "tech writer", I could
> assist by updating some of the screen shots and adding
> some examples.  I expect there are many others "readers" who could
> contribute examples or just FAQs with answers.
>
> It, the User Guide does need to be updated, which raised a couple of
> what are probably very basic questions.

Indeed, the guide needs to get updated for the upcoming 2.0 release.

> I am able to create an updated HTML User Guide by doing a  make in
> the gnucash-doc-svn  directory,  how do I generate
> the PDF files?

I'm afraid I don't know offhand.

> Are the existing screen shots reasonably stable?

What do you mean by "reasonably stable?"  I think we probably need a
completely
new set of screen shots for the 2.0 release.

> Is there a list of "standard" Names - GnuCash/GNUCash/GNUcash ?
> GnuCash seems to be most accepted correct ?

Yea, we should be using GnuCash.

> How should updates be feedback ?  svn -diff only resulted in errors.
> Would a tarball of a chapter and associated image fies
> be the preferred method?

What kind of errors do you get?   It's "svn diff", not "svn -diff".  You
should send a diff, not whole files.

> any suggestions or recommendations?

Please!  Go for it!

> Dave
>
> P.S. I started on the chapter on Investments (Chapter 8).  Sales for
> gains & loss seem to be an issue.

I'm hoping Jon will pipe up soon...   But yes, please.. Help with docs!

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Dave Herman
On Thu, 2006-03-23 at 18:56 -0500, Derek Atkins wrote:
> Hi,
>
[snip]


> > Are the existing screen shots reasonably stable?
>
> What do you mean by "reasonably stable?"  I think we probably need a
> completely
> new set of screen shots for the 2.0 release.
>
Any major changes to icon or overall GUI ?

[snip]

> >
> What kind of errors do you get?   It's "svn diff", not "svn -diff".  You
> should send a diff, not whole files.
>

Is this a issue with my system (FC4 Up to date) or with SVN defination
of file type.  I understand and expected the screen captures would fail,
however XML?

[dvherman@FedoraCore4Dev gnucash-doc-svn]$ svn diff
Index: guide/C/figures/invest_stockvalue_report.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: guide/C/figures/invest_peditor.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: guide/C/figures/invest_stockvalue.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: guide/C/figures/invest_peditor2.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: guide/C/ch_invest.xml
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = application/octet-stream
[dvherman@FedoraCore4Dev gnucash-doc-svn]$


> > any suggestions or recommendations?
>
> Please!  Go for it!
>

> I'm hoping Jon will pipe up soon...   But yes, please.. Help with docs!
>
> -derek
>
> --
>        Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
>        Member, MIT Student Information Processing Board  (SIPB)
>        URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
>        [hidden email]                        PGP key available
>

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Derek Atkins
Quoting David Herman <[hidden email]>:

>> > Are the existing screen shots reasonably stable?
>>
>> What do you mean by "reasonably stable?"  I think we probably need a
>> completely
>> new set of screen shots for the 2.0 release.
>>
> Any major changes to icon or overall GUI ?

Yeah..  Gtk1 -> Gtk2.  I would consider that a major change to the
overall GUI.
Wouldn't you?  ;)

[snip]
> Is this a issue with my system (FC4 Up to date) or with SVN defination
> of file type.  I understand and expected the screen captures would fail,
> however XML?
[snip]
> Index: guide/C/ch_invest.xml
> ===================================================================
> Cannot display: file marked as a binary type.
> svn:mime-type = application/octet-stream

Um, I would consider this a bug in the SVN attribute for this file.

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Dave Herman

I have a archive of my changes to the Concept/User Guide for GnuCash
Chapter 8 (Investments).  I've updated the screenshots, installed the
comments in the BZ reports that I've seen and modified some of the
grammar/spelling (also probably inserted some errors of mine).

The archive contains the new screenshots images, a DIFF between new XML
and the XML from 1.8.5 (the latest doc I found), and the new
"ch_invest.xml".

Suggestions on where to place this archive (1.2M) are needed, as are
reviewers.

This is a draft for comments/suggestions.

Observations from working on the update;

1) There appears to be inconsistencies in screen names and enter forms
using "commodity" and "security".  Working through creating new security
account (Guide 8.4.2) brings up a screen (New Account) to select
commodity, then a screen labeled "Select Security", then a screen "New
Commodity".

Should these terms be combined "Commodity/Security", defined, or
ignored?  Do you really track Commodities as "Corn, Wheat, ...)?

2) What is the proper term for the "mark" next to the account name that
signifies that there are sub-accounts present?


Dave Herman



_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Bengt Thuree
On Sat, 2006-04-08 at 14:00 -0600, David Herman wrote:
> I have a archive of my changes to the Concept/User Guide for GnuCash
> Chapter 8 (Investments).  I've updated the screenshots, installed the
> comments in the BZ reports that I've seen and modified some of the
> grammar/spelling (also probably inserted some errors of mine).
>

Hi

What tool did you use to modify the docbook?
A plain text editor like emacs, vi, gedit, scite or similar?
Or xml/docbook specific editor like conglomerate?
I tried conglomerate and liked it, but it do not show all the various
tags/text which means I can not use it.
Would prefere not to have to hack all the various xml tags manually...

/Bengt

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Bengt Thuree
In reply to this post by Dave Herman
On Sat, 2006-04-08 at 14:00 -0600, David Herman wrote:

> The archive contains the new screenshots images, a DIFF between new XML
> and the XML from 1.8.5 (the latest doc I found), and the new
> "ch_invest.xml".

1.8.5 ??
I can only find 1.8.4!

What am I missing?

/Bengt

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Josh Sled
In reply to this post by Bengt Thuree
On Sun, 2006-04-09 at 23:13 +0800, Bengt Thuree wrote:
> What tool did you use to modify the docbook?
> A plain text editor like emacs, vi, gedit, scite or similar?
> Or xml/docbook specific editor like conglomerate?
> I tried conglomerate and liked it, but it do not show all the various
> tags/text which means I can not use it.
> Would prefere not to have to hack all the various xml tags manually...

I recommend nxml-mode for emacs.  By itself it'll do on-the-fly
well-formedness checking of abritrary XML, but it also understands
DocBook's schema, and can thus do validation and tag-completion.

http://www.thaiopensource.com/nxml-mode/

--
...jsled
http://asynchronous.org/ - `a=jsled; b=asynchronous.org; echo ${a}@${b}`
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Question on modifing User Guide

Dave Herman
In reply to this post by Dave Herman
I use gedit 2.10.2.

Has some XML support, show balanced statements.

Sorry I really used 1.8.4 guess I just made an error in naming the
directory, and didn't check the diff when writing the e-mail.

Guess I investigate the EMACS tools, need to learn EMACS anyway.

Dave

Surprised at lack of response/interest to work on "Documentation"

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Bengt Thuree
On Mon, 2006-04-10 at 08:25 -0600, David Herman wrote:

> Guess I investigate the EMACS tools, need to learn EMACS anyway.
I am getting that feeling as well... Used EMACS long time ago, but now I
am a VI user, but feels weird to use VI/EMACS in a full GUI
environment... Unless I am deep into Unix configuration files...

>
> Dave
>
> Surprised at lack of response/interest to work on "Documentation"

Me too... Me too... Especially since "everyone" wants 2.0... and the
documentation is easy to help with, if nothing else than comments and
suggestions...

Did I miss anything in my mails? Perhaps I scared them away... :(

/Bengt

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Derek Atkins
In reply to this post by Dave Herman
David Herman <[hidden email]> writes:

> [dvherman@FedoraCore4Dev gnucash-doc-svn]$ svn diff
> Index: guide/C/figures/invest_stockvalue_report.png
> ===================================================================
> Cannot display: file marked as a binary type.
> svn:mime-type = image/png

Yea, you can't diff images...  You just need to upload the
new images so they can be replaced in-full.  Just send in
your new images when you send the update.

> Index: guide/C/ch_invest.xml
> ===================================================================
> Cannot display: file marked as a binary type.
> svn:mime-type = application/octet-stream

I've fixed this..  The .xml files should now be diffable.
You will need to "svn update" in gnucash-docs to get the
new properties.

Let me know if I missed any files.

-derek
--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Chris Lyttle
In reply to this post by Dave Herman
First of all Dave thanks a lot for doing this. If you want to submit
updates to the docs you can email them to me and I'll commit them to svn.

David Herman wrote:

> I have a archive of my changes to the Concept/User Guide for GnuCash
> Chapter 8 (Investments).  I've updated the screenshots, installed the
> comments in the BZ reports that I've seen and modified some of the
> grammar/spelling (also probably inserted some errors of mine).
>
> The archive contains the new screenshots images, a DIFF between new XML
> and the XML from 1.8.5 (the latest doc I found), and the new
> "ch_invest.xml".
>
> Suggestions on where to place this archive (1.2M) are needed, as are
> reviewers.
>
> This is a draft for comments/suggestions.
>
> Observations from working on the update;
>
> 1) There appears to be inconsistencies in screen names and enter forms
> using "commodity" and "security".  Working through creating new security
> account (Guide 8.4.2) brings up a screen (New Account) to select
> commodity, then a screen labeled "Select Security", then a screen "New
> Commodity".
>  
This should probably be submitted as a bug to be fixed before release
with more appropriate names.
> Should these terms be combined "Commodity/Security", defined, or
> ignored?  Do you really track Commodities as "Corn, Wheat, ...)?
>
> 2) What is the proper term for the "mark" next to the account name that
> signifies that there are sub-accounts present?
>
>  
I usually just refer to this as a '+' or plus symbol in the docs.

Chris
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Chris Lyttle
In reply to this post by Bengt Thuree
No you didnt miss anything, its fairly normal for only one or two people
to be editing docs.

Chris

Bengt Thuree wrote:

> On Mon, 2006-04-10 at 08:25 -0600, David Herman wrote:
>
>  
>> Guess I investigate the EMACS tools, need to learn EMACS anyway.
>>    
> I am getting that feeling as well... Used EMACS long time ago, but now I
> am a VI user, but feels weird to use VI/EMACS in a full GUI
> environment... Unless I am deep into Unix configuration files...
>
>  
>> Dave
>>
>> Surprised at lack of response/interest to work on "Documentation"
>>    
>
> Me too... Me too... Especially since "everyone" wants 2.0... and the
> documentation is easy to help with, if nothing else than comments and
> suggestions...
>
> Did I miss anything in my mails? Perhaps I scared them away... :(
>
> /Bengt
>
> _______________________________________________
> gnucash-devel mailing list
> [hidden email]
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel
>
>  

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Derek Atkins
In reply to this post by Chris Lyttle
Chris Lyttle <[hidden email]> writes:

>> 1) There appears to be inconsistencies in screen names and enter forms
>> using "commodity" and "security".  Working through creating new security
>> account (Guide 8.4.2) brings up a screen (New Account) to select
>> commodity, then a screen labeled "Select Security", then a screen "New
>> Commodity".
>>
> This should probably be submitted as a bug to be fixed before release
> with more appropriate names.

Note that these kinds of bugs should be filed /SOON/ because as
soon as we hit string freeze (in the next week or three) there
are no string changes at all until well after 2.0 is released.

>> Should these terms be combined "Commodity/Security", defined, or
>> ignored?  Do you really track Commodities as "Corn, Wheat, ...)?
>>
>> 2) What is the proper term for the "mark" next to the account name that
>> signifies that there are sub-accounts present?
>>
>>
> I usually just refer to this as a '+' or plus symbol in the docs.

Except it's a triangle, now -- or at least it's themable.

> Chris

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Dave Herman
In reply to this post by Chris Lyttle
On Mon, 2006-04-10 at 22:45 -0600, Chris Lyttle wrote:
> First of all Dave thanks a lot for doing this. If you want to submit
> updates to the docs you can email them to me and I'll commit them to svn.
>
The text changes are OK - I think, however I had some comments about the
images.  Specifically the title of the "window" i.e file names.  Give me
a day or two to cleanup.

Also - there is one screen that I have NOT been able to screen capture-
the options screen with the pull-down on the price date.  Alt-PrtScrn or
PrtScrn do not operate - any other suggestions.  The current image is
not incorrect just out-of-date.




_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Bengt Thuree

On On, 2006-04-12, 11:41, David Herman skrev:
> On Mon, 2006-04-10 at 22:45 -0600, Chris Lyttle wrote:

> Also - there is one screen that I have NOT been able to screen capture-
> the options screen with the pull-down on the price date.  Alt-PrtScrn or
> PrtScrn do not operate - any other suggestions.  The current image is
> not incorrect just out-of-date.
>

Use GIMP
Capture Window, with 5 seconds delay

/Bengt

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Bengt Thuree
In reply to this post by Dave Herman

On On, 2006-04-12, 11:41, David Herman skrev:
> On Mon, 2006-04-10 at 22:45 -0600, Chris Lyttle wrote:
> The text changes are OK - I think, however I had some comments about the
> images.  Specifically the title of the "window" i.e file names.  Give me
> a day or two to cleanup.
>

What do you think of adding some information on where to find the Stock
Symbol?

Like if you have European Stocks, you need to go to Yahoo-> Finance ->
Symbol Lookup -> search. Which will give you a <SYMBOL>.<MARKET> symbol
for this stock. This symbol should be used together with one of the Yahoo
markets.

/Bengt

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Tim Wunder (Lists)
In reply to this post by Bengt Thuree
On Tuesday 11 April 2006 10:57 pm, someone claiming to be Bengt Thuree wrote:

> On On, 2006-04-12, 11:41, David Herman skrev:
> > On Mon, 2006-04-10 at 22:45 -0600, Chris Lyttle wrote:
> >
> > Also - there is one screen that I have NOT been able to screen capture-
> > the options screen with the pull-down on the price date.  Alt-PrtScrn or
> > PrtScrn do not operate - any other suggestions.  The current image is
> > not incorrect just out-of-date.
>
> Use GIMP
> Capture Window, with 5 seconds delay
>
Or ksnapshot...

Tim
--
Fedora Core release 4 (Stentz), Linux 2.6.16-1.2069_FC4
KDE: 3.5.2-1.2.fc4.kde, xorg-x11-6.8.2-37.FC4.49.2
 06:50:01 up 3 days, 22:22,  1 user,  load average: 0.44, 0.24, 0.10
MP3/OGG archive Total playlength : 7 days, 21 hours, 42 mins 58 seconds
"It's what you learn after you know it all that counts" John Wooden

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel

attachment0 (198 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Question on modifing User Guide

Chris Lyttle
In reply to this post by Derek Atkins
I agree, please file this bug and mark it STRING in keywords so we know
a string change is needed.

Chris


Derek Atkins wrote:

> Chris Lyttle <[hidden email]> writes:
>
>  
>>> 1) There appears to be inconsistencies in screen names and enter forms
>>> using "commodity" and "security".  Working through creating new security
>>> account (Guide 8.4.2) brings up a screen (New Account) to select
>>> commodity, then a screen labeled "Select Security", then a screen "New
>>> Commodity".
>>>
>>>      
>> This should probably be submitted as a bug to be fixed before release
>> with more appropriate names.
>>    
>
> Note that these kinds of bugs should be filed /SOON/ because as
> soon as we hit string freeze (in the next week or three) there
> are no string changes at all until well after 2.0 is released.
>
>  
>>> Should these terms be combined "Commodity/Security", defined, or
>>> ignored?  Do you really track Commodities as "Corn, Wheat, ...)?
>>>
>>> 2) What is the proper term for the "mark" next to the account name that
>>> signifies that there are sub-accounts present?
>>>
>>>
>>>      
>> I usually just refer to this as a '+' or plus symbol in the docs.
>>    
>
> Except it's a triangle, now -- or at least it's themable.
>
>  
>> Chris
>>    
>
> -derek
>
>  

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel