bug#35261: 26.1; EBDB Documentation

[David Masterson <dsmasterson@outlook.com>]

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.

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.

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.

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

--
David