Detailed documentation?

Where can I find detailed documentation as to the meanings of all the fields in the database. It is kind of hard to use a program which is based on a database if there is no explanation as to what all the fields of the database should be used for.
  • edited October 20, 2010
    This might be what you are looking for: http://gsl-nagoya-u.net/http/pub/csl-fields/

    Then again, maybe not. Is your question about the UI, or about the underlying database itself?
  • also, the hope would be that most fields are self-explanatory - any specific doubts?
  • I am speaking of the field names shown in the user interface, in the right-most pane. The part where the user enters the data.

    fbenett, the link you provided is merely a translation chart to the names of fields used in other software. It does not actually explain what data should be put into those fields. But thank you for trying.

    Adamsmith, Hoping for one-word field names to be self-explanatory, in the context of bibliographic entries where the details of what to call what and what to put where have been debated ad nauseam for centuries, seems to me to be a false hope.

    While some database fields are relatively self explanatory, for most of the fields, it would be easy for people to have differing interpretations as to what data actually should be entered. In other cases I have no clue as to where I should normally expect to find such data.

    For instance:
    In the interview Item Type: does "Date" refer to the date of the interview or the date the interview was published? What is the "Medium"? Does it mean how the interview was conducted or how it was published? What are the appropriate words to enter here? "Telephone", "Telephone Conversation", or "Phone"? What should one enter for "Rights:" or "Extra:"?
    In the Statute Item Type: What the heck is the difference between the "Code" and the "Code Number"? Under "Date Enacted" do I enter the date the bill was voted on, signed, or when it went into effect?

    Heck I could ask similar questions about some of the names for the item types.

    Sure, I could spend a considerable amount of time asking individual questions about each and every individual field and discussing the ins and outs of all the various possible interpretations, but that would get terribly dreary. Why isn't there some set of documentation that simply describes every item type and all the fields in that item type and tells the user what to fill in there and why.

    A good program with poor documentation is an oxymoron. Yes, I know the program is free for me to use. However funders funded the development of Zotero, most likely with the hopes that it would be useful to many people and improve the quality of academic work. However, by not providing complete documentation the developers are short-changing the funder's and defeating their goal.

    So, I ask again: Is there complete and accurate documentation as to the data that goes in the fields in the Zotero database? If so, where can I find it?
  • User-accessible descriptions of every field are probably not written yet (and I can think of few reference managers--free/open source or proprietary that have this). Zotero is an open source project & documentation contributions are quite welcome.

    For your particular inquiries:
    In the interview Item Type: does "Date" refer to the date of the interview or the date the interview was published?
    I'd argue that 'interview' is mostly for unpublished types (otherwise, it'd be an audio/video recording or an article or a book section). I'd therefore suggest it was the date of the interview. This thinking (and perhaps lack of precision) is mirrored by style manuals (e.g. MLA) that have a separate interview type.
    What is the "Medium"? Does it mean how the interview was conducted or how it was published? What are the appropriate words to enter here? "Telephone", "Telephone Conversation", or "Phone"?
    Most citation styles call for the medium it was documented by (personal, telephone, email, etc.). There is not a canonical list of what to call these in most styles & zotero certainly does not confine you to a few enumerated types. Feel free to normalize your own data.
    What should one enter for "Rights:"
    The copyright license of the work (e.g. CC-BY)
    or "Extra:"?
    Whatever extra bit of information you want, which may be included in your bibliography (depending on the citation style). This is equivalent to BibTeX's 'note' field.
  • In the Statute Item Type: What the heck is the difference between the "Code" and the "Code Number"?
    http://forums.zotero.org/discussion/132/bluebook-statutes/
    Under "Date Enacted" do I enter the date the bill was voted on, signed, or when it went into effect?
    I assume you are not a lawyer? You are correct that the "enacted" date is not the same as the "effective" date, but I guess I don't see the ambiguity here...
  • In my defense - this isn't a question that comes up very often - so for most people, me included, most fields do seem to be self-explanatory.

    Apart from that your aggressive tone is quite unnecessary and unwarranted. Please keep it friendly and civil. Statements like "by not providing complete documentation the developers are short-changing the funder's and defeating their goal" aren't helpful.
  • edited October 20, 2010
    @GrantRobertson: Sorry I couldn't help. Good luck, and have a nice day.
  • Dear adamsmith,
    My aggressive tone comes from years and years of trying to get answers out of developers and users of both open source and shareware software, almost completely to no avail. I have had only somewhat better luck with commercial software. I am a former network manager and independent computer consultant with years of experience figuring out how software works and explaining it to less experienced users. It has become quite tiresome to look for adequate documentation and be told over and over again that "the question has never come up" and to just post questions in the forum or in newsgroups. Especially when the question involves the proper interpretation of dozens of aspects of the software.

    With most open source and shareware products it is reasonable to accept that it is the developer's prerogative as to whether they write adequate documentation or not. After all, if they only want a very narrow slice of highly technical people to use or buy their product that is up to them. One would think, however, that if someone put all that work into a product that they would want as many people to use or buy it as possible. The rampant disregard for adequate documentation simply boggles my mind.

    Zotero is in a different category in that several foundations put up money for its development. These foundations have stated goals of helping the public. I can only assume that they funded this project in hopes that Zotero would help increase the quality of academic writing and make it easier for students to properly cite their sources. One must remember that these students are in the process of learning about all this stuff. They are not experts in citation terminology or in the high-end web-based technologies that Zotero uses to extract the data from web sites or convert that data into the correct forms for citations. They couldn't care less about "translators" and XSLT and stuff like that. They just want their frikkin citations.

    A lack of proper documentation, especially for a product such as Zotero, seriously hampers the ability of average students to use the product. Therefore, it does, in fact, short-change the funders' goals of helping as much of the public as possible. Do you think the sponsoring foundations would have authorized those grants if the proposals had stated that the only people who would be able to fully utilize the software would be highly technical people? I don't think so.

    I do not say these things to be harsh. I say them in an attempt to spur the developers into action. Proper software design should START with the documentation so the developers know what their goals are. I would think the computer science professors at a prestigious university such as George Mason would emphasize that strongly. While I understand that "documentation contributions are quite welcome," it is not as if I could simply sit down and start writing. I would have to grill the developers about how each field is actually translated and used for each and every different citation style. In order to effectively do this I would have to actually move to Fairfax, Virginia and work with the developers for several months. Otherwise, I would only be able to write lot of guesses and mediocre explanations. I am an excellent technical writer, but there are limits to what a writer can produce when given poor information. Besides, I have my own project that I am working on (www.demml.org) which I believe is far more important than writing documentation that someone else should have completed a long time ago.

    Thanks to everyone who tried to help. I guess I will just have to muddle through as best as I can on my own.
  • For what it's worth - everyone who has responded to you so far is a full-time academic with an advanced degree in a not-computer related field. We've also all talked to many fellow academics, many of them less technologically about Zotero - none of which appears to be the case for you.
    So I think we have considerably more insight than you on how academics work and can do quite well without your lectures. I hope you don't think that anything you did here was constructive. Good luck on your project.
  • But, you see, adamsmith, that is my point. I have hopes of becoming an academic but am not one now. I don't have an advanced degree and I don't have years of experience writing academic papers with full and proper citations. I, like millions of other students, need documentation as to how to use the software precisely because we do not already have advanced degrees. If, as with most professional academics, you and your colleagues are working under funding from various grants, then you have been paid by your funders for the extra time you had to invest to learn how to properly use Zotero. If there had been proper documentation then you would have had more time to work on the actual projects your funders were funding. All the rest of us have to learn how to use the program on our own time.

    I concede that you have more insight as to how academics work. But can you concede that I may have more insight into how students and users who are simply trying to get their papers written may feel. If the Zotero funders and developers have any hopes of this program being used by regular students - in addition to professional academics - then it is imperative that they provide full and proper documentation, written in a manner that is understandable by those regular students.

    It is funny, in a sad way, that this is the same response I have gotten almost every time I attempt to convince people that proper documentation is needed. Even in forums where regular users are continuously threatening to switch to a different product because they can't find such documentation. It is almost as if those who have invested the time to learn a product somehow enjoy their special status as "experts" and resent the notion that the skills they have worked so hard to obtain could somehow be made available to others in a much less work intensive fashion.

    I am sorry if you have taken offense at my simple request that adequate documentation should be provided if the developers and funders of Zotero have any hope of the product having any real impact in the community of new scholars currently learning how to do good academic work. It is unfortunate that you have found it necessary to defend the status quo with ad hominiem attacks as to my insight into "how academics work." Especially when my insight in that area is actually quite irrelevant in regards to whether there is enough documentation for non-academics to use Zotero easily. I am not lecturing you personally as to how to do your academic work. I am making a statement directed at the developers. If the level of documentation is good enough for you, then fine. But I am simply saying I don't think it is good enough for all the rest of the world that may benefit from Zotero.
  • edited October 21, 2010
    Everyone responding to you so far in this thread has been volunteering hours every day for years to help everyday users of Zotero, and for you to condescendingly suggest that you have a better idea how to help those users is offensive and the height of absurdity.

    If you'd like to contribute documentation, you're welcome to do so. Given that Zotero developers are in fact spread throughout the world and answer (much more polite) questions in these forums every day, I wouldn't buy that house in Fairfax just yet.

    But at this point you're just wasting people's time, and I'm closing this thread.
This discussion has been closed.