I need some advice on the structure of the manual, and help with entries.

[Craig Earls]

After languishing for longer than I am happy to admit, I am getting back into the manual.  I have the same problem now that brought me to a dead stop several months ago: the overall structure.

Ledger is incredibly complex, and, frankly, I am at a loss on how to really approach it correctly.  Some parts of the current manual are tutorial in nature, other parts are list of command options.  They don't flow together and it isn't even clear to me where I should look to find anything in particular.  So I beg you to give me some suggestions to help break through this block.

Also,  there are many, many entries in the lists of options/cmmands that say FIX THIS ENTRY. Because I don't have a decent understanding of some of the more arcane ones.  If you see one that you understand please submit an entry to me.  

--
Craig, Corona De Tucson, AZ
enderw88.wordpress.com

[Peter Keen]

On Thu, Oct 4, 2012 at 1:45 PM, Craig Earls <ende...@gmail.com> wrote:

After languishing for longer than I am happy to admit, I am getting back into the manual.  I have the same problem now that brought me to a dead stop several months ago: the overall structure.

Ledger is incredibly complex, and, frankly, I am at a loss on how to really approach it correctly.  Some parts of the current manual are tutorial in nature, other parts are list of command options.  They don't flow together and it isn't even clear to me where I should look to find anything in particular.  So I beg you to give me some suggestions to help break through this block.

I think two main sections would be good. One section would be the tutorial and "Keeping a journal with ledger" content, and the other section would be strictly reference, organized by subcommand. Global options before the subcommands, subcommand-specific options within their respective sections. Formatting and expressions probably deserve their own part of the reference section as well.

[Craig Earls]

for the reference section do you prefer tabular format with shorts descriptions, or long form prose with longer explanations for each command, or both?

[Peter Keen]

On Thu, Oct 4, 2012 at 2:33 PM, Craig Earls <ende...@gmail.com> wrote:

for the reference section do you prefer tabular format with shorts descriptions, or long form prose with longer explanations for each command, or both?

I would prefer a tabular format for options and longer-form prose sections for subcommands. For example (using Markdown syntax):

## Global options

`-f, --file` *FILE*

:  Load ledger data from FILE. This overrides the settings in ~/.ledgerrc and the LEDGER_FILE environment variable.

## Commands

### bal

Run a balance report. <insert long description of balance report here, including short self-contained examples>

<insert balance report specific options here>

[Eric Abrahamsen]

I think some of the sections might be a little overloaded right now: the
"Transactions" section in particular has a *whole* lot of information
that I wouldn't necessarily expect to be found under "Transactions".

For instance, the "Journal Format" node is under "Keeping a Journal",
yet metadata isn't mentioned until "Transactions/Metadata". I would have
looked to "Journal Format" to explain metadata, or at least mention its
syntax. There are also multiple sections on currency and commodity, some
describing concepts, some describing formats, and others describing
command options, with quite a bit of overlap.

There are several other issues like this, that might make the manual a
little confusing at first read. Don't get me wrong, this is a huge
amount of work and I'm *very* glad someone's doing it! Everything we
need to know is in there, it could probably just use some
re-organization.

Generally I think there should be a clear distinction between a few
types of content: "concepts/tutorials", "journal format", and "command
options".

Obviously there will be overlap and crosslinking, but it seems like we
might want conceptual "howto" sections -- what is double-entry
accounting, structuring accounts, working with currencies, keeping
virtual accounts, budgeting -- up front. I strongly feel that "Ledger
Format" should be a top-level node, with subnodes for things like
commenting, metadata, virtual accounts, etc.

I'm embarrassed to say I only discovered recently that I was still
reading the 2.X manual, so I'm not completely familiar with the new one.
If you think it would be helpful, I'd be happy to spend a little time on
more concrete suggestions for re-organization.

Thanks again for your work! As others have said, a complete manual is
nearly as important as having the program itself.

Eric

[John Wiegley]

>>>>> Peter Keen <peter...@bugsplat.info> writes:

> I think two main sections would be good. One section would be the tutorial
> and "Keeping a journal with ledger" content, and the other section would be
> strictly reference, organized by subcommand. Global options before the
> subcommands, subcommand-specific options within their respective sections.
> Formatting and expressions probably deserve their own part of the reference
> section as well.  

I agree with this. There should be a tutorial that leads into a user's guide,
then a cookbook for typical "recipes", and finally a comprehensive reference
on things like value expressions, query expressions, format strings, etc. The
ref manual will naturally evolve over time, so maybe the focus right now
should be on the tutorial/user's guide/cookbook. Thoughts?

John

[Craig Earls]

Should we have two separate manuals?  Users and Reference?

On Thu, Oct 4, 2012 at 8:30 PM, John Wiegley <jo...@newartisans.com> wrote:

I agree with this.  There should be a tutorial that leads into a user's guide,
then a cookbook for typical "recipes", and finally a comprehensive reference
on things like value expressions, query expressions, format strings, etc.  The
ref manual will naturally evolve over time, so maybe the focus right now
should be on the tutorial/user's guide/cookbook.  Thoughts?

John

[John Wiegley]

>>>>> Craig Earls <ende...@gmail.com> writes:

> Should we have two separate manuals?  Users and Reference?

At some point, but right now let's go with one manual that has two parts.
That way, people don't have to search in two different places.

John

[Craig Earls]

I will start parting the red sea tomorrow.  BTW, I am sorry I let you down, this was supposed to be done MONTHS ago...

[John Wiegley]

>>>>> Craig Earls <ende...@gmail.com> writes:

> I will start parting the red sea tomorrow.  BTW, I am sorry I let you down,
> this was supposed to be done MONTHS ago...

No worries, Craig, I admire whatever you're to do to help.

John

[rubén gómez]

>>>> Craig Earls, o 04 Out, 13:45:

> Ledger is incredibly complex, and, frankly, I am at a loss on how to really
> approach it correctly. Some parts of the current manual are tutorial in
> nature, other parts are list of command options. They don't flow together
> and it isn't even clear to me where I should look to find anything in
> particular. So I beg you to give me some suggestions to help break through
> this block.
>
> Also, there are many, many entries in the lists of options/cmmands that
> say FIX THIS ENTRY. Because I don't have a decent understanding of some of
> the more arcane ones. If you see one that you understand please submit an
> entry to me.
>

If helps I attached a screenshot of my personal wiki ledger's page.
When I started with ledger found a mess of information in the manual
then I decided to create my own one to try to learn all ledger's
power and for quick reference.

I mixed ledger and hledger manual, internal help and comments in
code to create it and this is the result (work in progress).
Sorry, it's in my own language (galician).

It's structured in 4 blocks each one corresponding to the different
parts that compose a ledger's command:

$ ledger COMMAND QUERY OPTIONS ARGUMENTS

And an extra block (APPENDIX) with tips, howtos...


You can see in the screenshot but I put here the structure in english
for clarification:

COMMANDS
- main: balance, register, print, budget, cleared, equity
- list: accounts, commodities, prices, payees, stats
- output: csv, xml
- debug: args, eval, format, generate, parse, python, template

QUERY
- types: regex, payee, tag, note, code
- logic: and, or, not, ()

OPTIONS (see screenshot for full list)
- general: help, full-help, version, file...
- mainly for balance: basis, collapse, collapse-if-zero...
- mainly for register/print: average, deviation, current, effective...
- mainly for print: raw
- mainly for accounts/commodities/payees: count
- limit and group: period, period-sort, begin/end, dow, daily...
- commodities variation: exchange, gain, market, now
- output: amount, total, date, percentage, wide, columns...
- debug: args-only, verify, verbose, debug, trace
- unknown to me: base, cache, exact, generated, import...

ARGUMENTS
- PERIOD: every, daily, from/since...
- DATE: last, this, next...
- CONDITION:
- function: -, U, S, A, P
- variable: t, T, m, d, a, b...
- operator: * / + - ! < > = & | ?:, not, neg...
- expression: {N}, W/regex/, p/regex/...
- FORMAT

APPENDIX
- journal: format, directives, automatic/virtual registers, closing
year, blance verification, time manager
- commodities
- budget/forecast

I hope it can help :-)

[Craig Earls]

Thanks you, that is a very clean way of presenting everything.

On Tue, Oct 9, 2012 at 12:41 AM, rubén gómez <ruben...@canselleiro.org> wrote:

>>>> Craig Earls, o 04 Out, 13:45:

> Ledger is incredibly complex, and, frankly, I am at a loss on how to really
> approach it correctly.  Some parts of the current manual are tutorial in
> nature, other parts are list of command options.  They don't flow together
> and it isn't even clear to me where I should look to find anything in
> particular.  So I beg you to give me some suggestions to help break through
> this block.
>
> Also,  there are many, many entries in the lists of options/cmmands that
> say FIX THIS ENTRY. Because I don't have a decent understanding of some of
> the more arcane ones.  If you see one that you understand please submit an
> entry to me.
>

--

[Jeroen De Vlieger]

That is indeed a good proposal.

As a newbie to both double entry accounting an the ledger tool.
I find that I would love to see more tutorials and recipes to do basic and common actions.
a sort of user guide like John mentions that introduced concepts, cmd line options, value query examples in a goal driven format!

Stuff like keeping track of expenses, how to do budgetting, how use the balance cmd effective,  reconciling your bank statement, using the virtual accounts.
could gradually introduce more and more options and command without overloading a newbie.
This way your features are also introduced with a reason.

A reference, e.g, a list of all possible cmdline options *alphabetically* ordered is the ideal way to go if you want to remind yourself on some obscure cmd option that you use only every so often.

But If you are played with how to effectively implement some budget control, then being forced to read a reference type of work, e.g., this list of alphabetically ordered options and commands is rather bothersome and not at all motivating. It will even leaves a user  iwith more questions than anwers, wonderiong why certain options are ever needed.  And he might never even find out if his workflow never reaches that point where there is a problem that gets solved by that specific cmd or option.

In those cases a refence or list of all possible options and command is not the right way to go. A goal driven 'user guide' how ever would be so much more appealing. A new user could simply learn what he needs to know by searching for a relevant usecase of tutorial and be remain shielded of the rest of the multitude of options.
IMHO It is this kind of goal driven userguide that will be crucial for people giving the project an initial try to be convinced and stick with it instead of leaving it in favor of some other project that will hopefully be more user friendly to newbie's and the likes.




A reference manual is a complete description designed to easily look something up
A user guide contains the same information  or more realistically part of it and refers to the reference manual if need be, but is designed as a getting started document, introducing the information grouped in a goal driven fashion.

A reference requires that you either read it start to end in order to understand it, or have earlier obtained knowledge about used terms and concepts allowing you to understand the potentially cryptic explanations individual options, commands and features.
A userguide should be structured more freely, i.e. in a way that a new potential user can cherry pich the use-cases and tutorials that he thinks will be relevant for him to get started, without the fear of missing out on important information by skipping certain parts or being unable to properly understand certain  concepts.

For example, what I'm lacking at the moment is some quick and dirty getting started guide.
1) How to *initialize* your journal to your current state of affairs.
  + The amount of money on your bank accounts.
  + a generally accepted workable account structure that will meet most initial needs to get any one started. Especially for people like me that are not version in accounting this turns out to be a large stumble block.
  + how to Reconcile/import historical liabilities and reimbursements that aren't paid off. I.e. they are liabilities and reimbursements that you incurred prior to staring using ledger and building jour journal file with transactions.
  + How to reconcile/import historical expenses to build a *partial* *historical* expense report. Note that these will inherently be *incomlete*, so reconciling might be a beter suited word then importing in this use case.

2) a generally accepted workflow to keep on using the ledger tool.
This is also an issue that I still haven't yet solved satisfactorily, and I have been spending quite some time reading the manual.
Examples:
  + a system on how to effectively handle receipts to keep your yournal up to date with minimal effort
  + a system on how te reconvile your bank statement with your journal in an easy  enough way so that you keep on doing it.
  + a system to identify identical transactions from different sources and merge the information. This is where I still have lots of trouble and is turning out to be a large hurdle for me to solve. Source documents for transactions can come from a lot of different sources and they may be more then one document for each transaction. In those cases you need a proper system to successfully identify a transaction that has already be posted to the journal, potentially update it with some extra info included in the redundant source document and then simple archive the source document as processed. This whole workflow is one that I still find rather *challenging*  :-s
 + procedure on how to reconcile your ledger if errors somehow crept up.
 + etc...


sincerely,

Jeroen

[Jeroen De Vlieger]

A word of caution the next question goes more to accounting then to the ledger project itself :-s

I'm not yet completely through the documentation, but I can already log my transactions in a journal file and this is starting to fill up nicely with data.
So now I'm coming to the point that I won't to use ledger as a tool to manage my finances. I.e. I'm starting to think along the lines of:
 + how can I use ledger help me manage my financial situation.
 + how can I use ledger to help my analyse all this data and help me prevent financial hickups instead of being forced to solve them when they occure.

This is also one area in which I find the documenation to be a bit lacking.
I know of the balance and register command and the -M option, but how do I now use these to help me in my quest to manage my finances.
Which queries should I be runnig often? which reports should I be generating to inform me of what exactlly?

Of course you could decide that that information falls outside the scope of ledger, but even then I would argue that references to such information should be included in the ledger documentation, wheter it be in the reference manual or the user guide.

Jeroen

[Jeroen De Vlieger]

I.e. some section on how to analyse your journal data using ledger and interpret the results would be a very nice addition to a user guide IMHO.

[Craig Earls]

Jeroen, I very much appreciate your suggestions.  I have been thinking along the same lines myself.  

[Johann Klähn]

Craig,

one thing you should consider including is a link to the regex syntax
ledger uses as there are several styles.
I think perl style regular expressions are used by ledger. You could
provide this or another link
http://www.boost.org/doc/libs/1_51_0/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html

[Craig Earls]

Ooohhh.  Good one.  Thanks!