On Friday, October 5, 2012 5:30:09 AM UTC+2, John Wiegley wrote: > > >>>>> Peter Keen <[email protected] <javascript:>> 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 >
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
