bug#35261: 26.1; EBDB Documentation

[Eric Abrahamsen <eric@ericabrahamsen.net>]

On 04/15/19 03:50 AM, David Masterson wrote:
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> David Masterson <dsmasterson@outlook.com> writes:
>
>>> This is a documentation problem for EBDB.
>>>
>>> The documentation lacks clarity on how to setup EBDB for the first time
>>> in the case where you are *not* converting from BBDB or Org Contacts.
>>> More information is needed on how to create an EBDB database for the
>>> first time, how to setup the first record(s) that you put into the
>>> database, and (perhaps) an example session.  As it is, the documentation
>>> is too esoteric for someone unfamiliar with EBDB (or BBDB) concepts to
>>> make heads or tails of it and get their feet wet.
>>
>> Thanks for this report. Here's what the docs have now:
>>
>> Assuming you have no records you want to migrate from other contact
>> management software, it is enough to call the top-level ~ebdb~ command.
>> This will create a new database at the location specified by
>> ~ebdb-sources~ (see [The EBDB Database]), prompt you for a search
>> string, fail to find anything (because you don't have any records yet),
>> and finally open a EBDB buffer where you can start to make new records
>> (see [Creating Records]).
>>
>> This is correct, though admittedly terse! I suppose I could break this
>> out more specifically: you should set `ebdb-sources' in advance. Then
>> you can create your new database either by calling the `ebdb' command,
>> or by associating EBDB with a mail user agent, and letting that agent
>> create records for you.
>>
>> Or perhaps, if you have no records, the `ebdb' command could simply open
>> an *EBDB* buffer and then tell you, "you have no records, use 'c' to
>> create one"?
>>
>> WDYT?
>
> First, in the "Getting Started" section, there are the two subsections
> on migration.  At first glance, I assumed (incorrectly) that those were
> the ways to get started and missed the rest of what was said at the top
> level.  Therefore, I might suggest that the top level "Getting Started"
> section be an short intro to EBDB with (perhaps) references to key
> variables for setup.  Then have three subsections (or more) where the
> first in creating the database from scratch, second is migration from
> BBDB, and third is migration from Org Contacts.

That makes sense.

> Second, the top-level should probably reference where to find the
> internal details of the database structure and record structure(s).
> This should also be in the subsections to some degree.  Perhaps the
> top-level should simply reference the details in the sub-levels.

Ditto.

> Third, the creation process should probably have an example script to
> show the user what to expect.  In particular, I get an error when I try
> to create my first record in EBDB using 'c'.  I'm not sure if it is a
> problem with not having setup a database variable, record variable,
> record structure variable, or what.  I'm just beginning to experiment
> with EBDB, but I'm familiar with the concepts.  Emacs/EBDB and its
> extensive variables can make it difficult to determine where to start to
> configure things if the Info page doesn't lead through it.
>
> Fourth, having 'c' tell you that "you have no records" is not to helpful
> in that what you need is how to setup to create records.

This doesn't seem right: it's the `ebdb' command that tells you the
database is empty (and that message should include a mention of 'c').
'c' prompts for the creation of a record. Do you remember what sort of
error you got during record creation? There shouldn't be anything you
have to do in advance, except maybe confirm that you want to create a
new database at the default location.

> Fifth, there is no EBDB mailing list to ask questions on??

I don't think new mailing lists are made for specific packages very
often any more. In the case of EBDB, you can open an issue on the github
page, email me directly, or do what you've done here, which is just
fine (so long as you cc me). There's been some talk in the past about
having the bug reporter prompt for specific packages to report bugs
against, but that hasn't gone anywhere yet.

Yours,
Eric