Writers Guide: Bibliography section partial review

LibreOffice 7.5.1.2
Win11-64
WG75-Writers Guide
GS74-Getting Started

This is not a criticism. You have a great product and I enjoy using it. It is an analysis of faults, a critique, meant to (at least) state what is confusing to me. I am just beginning to use the LibreOffice bibliography and have thought to read the documentation before I use the facility. These are some of the things that I have found.

The WG75-Writers Guide Bibliography section needs a review. I think that it contains legacy items no longer used, it contains page numbers which are inaccurate, cyclic references to GS74-Getting Started, contradictory descriptions (of the identifier field), figures which donā€™t match the text and other things.

As in all reviews, take this one with a grain of salt and aspiration level laughter.

Some issues:
[1] This is the primary source for the Writer application. The ā€œGetting Started Guideā€ is not the primary source for any application, it is only an aid. Either rename ā€œGetting Startedā€ or ensure that all primary source documents are standalone and need not reference Getting Started. If you elect to continue using the Getting Started Guide as is, then references to this Guide should be direct references to a section in the Guide rather than to the Guide itself. The normal inference on a reference to the Guide is to look for the current topic, in this case Bibliographies. There is not much content from pg. 87, Creating Bibliographies and Indexes, in the Getting Started Guide to the end. If more than an overview is required then address the needed section(s) directly.

[2] Reference to the bibliography section of the Getting Started Guide are cyclic and non-informative. the Writer Guide references the Getting Started Guide which references the Writer Guide for bibliographic information.

[3] A brief referential section seems needed to identify and name, for this document, various items to be covered. Amongst the terms that should be clearly defined are:
a. references: particularly if this means Insert->Field->More Fields items.
b. citation.
c. citation record.
d. citation format.
e. citation style.
5. bibliographic database containing citation record.
g. global bibliographic database.
h. local bibliographic database.
i. embedded bibliographic database.

[5] Some information which needs addressing concerning citations, citation records, and the bibliographic database:
a. What happens when the original file is renamed, moved to the same filesystems, moved between computers.
a. What happens when the file is output in another format (docx, pdf, epub, text, ā€¦)
a. What are the issues with embedded, local, global bibliographic databases and renaming, moving.

[6] The Identifier/Short Name field has conflicting definitions.
a. pg. 355 Citations, eg, APA, MLA. Chicago, etc, use the Identifier field.
b. pg. 356 Replace sample entries with the proper citation style format.
c. pg. 357 Enter an entry name in the Short Name box. Should be unique.
d. pg. 357 Enter [Author, date].
e. pg. 360 Select a (ed. unique) reference from the Short Name drop-down
f. pg. 360 Type a unique name.
g. pg. 361 Use the text recorded in the Short Name field.

The conflicts are in the uniqueness requirement and a., b., d. in that uniqueness is not guaranteed, and in the usage in a., b. and for example, c. and d.. 

[7] I suspect the pg. 355 Citation Style section is a legacy item and should be removed. If it is not then some or all of the following apply:
a. The conflict in use of the Short Name Field has been noted.
b. What each style looks like is nowhere supplied.
c. External references defining the styles are not supplied.
d. External references to get additional styles other than the 4 main styles is not supplied.
e. What ASCII text is to be used for these and other citation styles in the Short Name Field.

[8] The word ā€˜Citationā€™ is used in multiple contexts. As a ā€˜citationā€™ style, a bibliographic entry in the database, a reference to a bibliographic entry in the document, and a bibliography entry in the document. This is confusing.

[9] Nowhere are the database fields, except the Identifier field, defined.
a. The Type field and its relationship to pg. 362 Figure 369 is undefined.
b. The relationship between fields and Type format is undefined. Which fields are needed for which output forms.
c. Conflicts in Identifier formats are unresolved, eg, an author creates multiple entries on the same day or in the same year, this makes the Identifier non-unique which is allowed. How is a reference to one of this non-unique names made.
d. How are multiple editors, authors entered.
e. What is the difference between and organization and an institution.
f. and so on.

[10] Which documents can have a bibliographic database, writer, calc, impress, ā€¦, and how are the references represented. Other documents should be cited, and this information should be put into the Getting Started Guide.

[11] pg. 355 Tip.
a. ā€œWriter has a single bibliography database for all documentsā€, this is clearly inaccurate.
b. Provide a reference to the relevant template information. If in-document, then link to it. The Getting Started Guide provides for Creating index and bibliographies provides no useful information.

[12] Note:
a. Nowhere are the citation record fields related to a citation format/style.
b. Clarification between ā€˜citation formatā€™ and ā€˜citation styleā€™ seems warranted.
c. Change ā€œsingle entryā€ to ā€œcitation recordā€. Note that multiple names are used for the same thing.

[13] Caution. The Short Name Field usage needs further definition.

[14] ā€œChanging the data sourceā€ The concept ā€œData Sourceā€ is undefined. The use of a Data Source depends on the definition of a local bibliographic database which is also undefined. The distinction between a data source which is a global bibliographic database is also undefined. The definition of ā€œglobalā€ in the context of a Writer is also undefined. At this point, ā€œChanging the data sourceā€ has no meaning.
a. What is unaddressed is that when the data source is changed, it is changed for this instance of the LibreOffice application. If several documents are open, each with a different local bibliographic database, then all but one will have a valid bibliographic database, the rest will have an invalid data source, i.e., the one that has been changed. If this statement is accurate then this is a flaw in LibreOffice. It does not allow several articles to be open, each with its own data source, to be changed in parallel. Instead, each time the subject of the changes are shifted, the data source needs to be changed.
b. It might be more appropriate to say ā€œChanging the bibliographic databaseā€.
c. What happens to the global example data source if a new version of LO is used. What happens to any changes made?

[15] ā€œFiltering recordsā€ No rationale is given as to why this is needed or desired. What is the object of record filtration?
a. The legends in the form are undefined.
b. The fields are undefined.
c. The processing algorithm is undefined.
d. Missing is ctrl-shift-F4->{auto filter, apply filter, standard filter, reset filter}
e. Missing is Tool->Bibliographic database->{auto filter, standard filter}

[16] ā€œAdding entries to the databaseā€
a. 1) change ā€œrecordsā€ to ā€œcitation recordsā€.
b. 2) Note that ctrl-shift-F4->Edit Data adds a citation record which can be edited if and only if its predecessor record has an entry.
c. 3) ā€œEnter nameā€, note previously identified duplicate meanings. Note also that some meanings preclude the entry from being unique. Note that there is no identified way to create citation references with duplicate citation record names.

[17] ā€œMaintaining entries in the databaseā€
a. ā€œentriesā€ should be changed to ā€œcitation recordsā€
b. ctrl-shift-F4 allows citation record modification.

[18] ā€œColumn detailsā€
a. A ā€œcolumnā€ has not been described. The distinction is important. There are more database types than Codd Relations, and in most a column has no meaning. It might be better to define a citation record independently before this point, and to relate the citation record fields to the UI legends and field contents, to the database presentation format in Tools->Bibliographic database or ctl-shift-F4. Then to state that the presentation format for citation records in the bibliographic database looks like a spreadsheet, and that each citation record field is a column in this presentation. The document did say that the bibliographic database looked like a spreadsheet but a little more wordage may be in order. Note that showing the UI and not stating the direct relationship to a citation record is deceptive, as well as the citation record ā€˜columnā€™ names are not the same as in the UI, for example, 'University" is a ā€˜Schoolā€™.
b. Figure 361 and Figure 363 are both missing ā€œLocal Copyā€, and that ā€œLocal Copyā€ is not in the citation record and as a result, there is an error each time Tools->Bibliography Database is used.
c. The UI in Figure 361 and 363 are different. Does that difference in content warrant a discussion?

[19] ā€œField detailsā€ you are depending on your reader to understand what a ā€˜fieldā€™ is.
a. ā€˜levelā€™: You probably mean to say something line the sidebar on the left shows hierarchical trees, one for each registered citation database. Select the database being used and click on each level to get to the citation record entry, that is ->Tables->, then left click on . In our example this is Bibliography->Tables->biblio. Otherwise, "levelā€™ has no meaning.
b. 3) or 5) Right-click the citation record entry (ed. or select the column/field) ā€¦
c. 5) in my version of LO I get Figure 365 not Figure 366.
d. 5) Where is anything in Figure 366 defined?
e. 6) where is the ā€œField Typeā€ anything?

[20] Figure 361 UI looks better than the flat field look in LibreOffice.

Iā€™m sorry. I just ran out of time. The document needs some clarification and a critical review. Most particularly, some attention to defining things and using consistent names throughout the document.

1 Like

Hi @ostbits (Arthur)

Thank you for the valuable inputs.
The review of the bibliography will demand some effort from our team but it is noted for later work.

Cheers
Olivier

Hi @ohallot;
Did you want me to write something?

I have almost zero knowledge of the bibliography, but most of the issues addressed are related to the presentation of concepts and that i might be able to write something about.

art

Hi @ostbits

Indeed that will be very nice. The chapters are available in our cloud folder. Are you aware of our editing process (access to the cloud, editing best practices, controlling updates and more)? If not, let me know and Iā€™ll guide you.

Chapters are in
WG75

GS74

Cheers
Olivier

Ah Ha; I can finally get to send a message. Sorry about the delay. To make a short story long, I use an email redirector. The redirector receives all email and then redirects it to my ā€˜realā€™ email address. When I join an email group I reflexively use my email redirector as my email address. When I reply to emails, my true email address is presented, and is rejected. Alas, thatā€™s the state of affairs. I replied, the reply was rejected, and now i am on vacation.

What this means is that i would like to contribute but I feel that any contribution I make will not follow the outline or format of documentation that I have seen. It is my feeling that the existing format does not address the problems to be had adequately. Rather than waste your time, and increase my frustration, I solicit your comments on whether (perhaps) dramatic format changes to this one section would be acceptable.

It is clear to me that there are several topics of more than casual concern (to me) which should be addressed in the bibliographic section. But, I donā€™t have an answer to them. Most particularly, I think some attention needs to be spent of creating a bibliographic database from scratch, and by copying the existing database, and then to allow renaming or exporting the database to other computers.

In addition, all of the record fields need to be addressed. What they do and how they are integrated into the overall scheme of things.

In addition, the ā€œLocal Copyā€ ā€˜fieldā€™ is not part of the bibliographic citation record, and as a result, each Tools->Bibliographic Database causes a pop-up to indicate that the review of the record is required. This is a bug in the implementation which should be corrected.

In addition ā€¦

So you see I am full of ideas. The issue is this ā€˜full of ideasā€™ productive to your efforts or should we just call it quits.

art

@ostbits Apologies for the delay in responding to this thread. Thank you for the detailed review.
Various people (over many years) have said that LOā€™s bibliography feature itself needs much work, well beyond what could be dealt with by improving the documentation, though creating a new or replacement sample bibliographic database could help. I donā€™t use this feature, so I have not looked into possible improvements in any detail. From this review, I suspect that a thorough discussion would best be done in a separate document, not as a chapter in the Writer Guide. If we do that, it need not follow the same format.

Thanks for the reply. I guess Iā€™d better be brief. I have volunteered my services to support documentation changes, this has been met with silence. Given that silence I chose not to report the additional 12 or 13 (apparent) bugs that I found.

I have discussed my own experiences with @ajlittoz and from him found out that his experiences are not dissimilar. He produced a document which was rejected by LO for being too technical. I have read his document and found it clear, concise, and technical enough so that a person needing to know the details of the functions described would find them. My comment at this point is what does ā€œtoo technicalā€ mean to an organization attempting to explain the technical to an audience.

My feeling is that the Bibliography function needs to be rearcharchitected and reimplemented, with documents describing the implementation. Based on my own experience and that of @ajlittoz it is difficult to see how I can aid in this process.

LO seems not open to change. What I see is an organization which says "do it my way, and suggest nominal changes to ā€˜do it my wayā€™ or they will be dismissed.

I am an experienced developer (at least 54 years) used to archtiecting systems, implementing algorithms, developing systems and code designed to be changed, analyzing documents and products, and producing them. I fear that I donā€™t have the experience to support LO, other than to moan.

thanks again
art