UI spec for CSL WYSIWYG wizard

Hi all,

as I had indicated to Bruce earlier, we (Mendeley) would like to pitch in on
developing a CSL creation wizard. The idea is to create a web app (hosted on
www.citationstyles.org) that allows users to configure citation styles
without requiring any programming skills.

I’ve now written up a UI spec document with interface mock-ups/wireframes
that would benefit from everybody’s comments/input. It’s currently in Word
document format - any preferences how best to share it? Should I transfer it
to a wiki (which one/where?), upload it to Google Docs…

Thanks and all the best,
Victor–
Victor Henning
Founder & Director

Mendeley
112 Clerkenwell Road
London EC1M 5SA
United Kingdom

Mail: @Victor_Henning
Web: http://www.mendeley.com
Tel.: +44 (0)207 253 1595

Registered Office: Cardiff House, Second Floor, Tilling Road, London NW2
1LJ, United Kingdom
Registered in England: No. 641901

Hi Victor.

Hi all,

as I had indicated to Bruce earlier, we (Mendeley) would like to
pitch in on developing a CSL creation wizard. The idea is to create
a web app (hosted on www.citationstyles.org) that allows users to
configure citation styles without requiring any programming skills.

I’ve now written up a UI spec document with interface mock-ups/
wireframes that would benefit from everybody’s comments/input.

Great!

It’s currently in Word document format - any preferences how best to
share it? Should I transfer it to a wiki (which one/where?), upload
it to Google Docs…

How complex is the document? Who is looking to comment on/contribute
to it?

If we did the wiki, the bitbucket project I setup has one that would
suffice.

Actually, on second thought, why not just do Google Docs now? We can
always move it later if we feel the need.

Hm, so much for that. Uploaded it to Google Docs, but it looks terrible -
formatting gone awry and screenshots/wireframes barely readable due to the
image resolution being too low.

I think transferring it to a wiki would work best. The document isn’t that
complex; it’s just a rough draft, 7 pages long. Since I have no experience
with BitBucket, how about I just create a page here?
https://sourceforge.net/apps/trac/xbiblio/wiki

Best,
Victor

The two work similarly. You can add it there, or somewhat preferably, here:

http://bitbucket.org/bdarcus/makecsl/wiki/UIProposal

Just let us know when you’ve got it setup.

Thanks,
Bruce

I see you added it; I’ve made a few minor edits, but have one big
issue we all should discuss, because it goes to the heart of the
matter:

It seems your proposal puts the central UI focus on modifying
"document types." I know there’s precedent for this, but I don’t think
it’s a very good idea.

In my UI mockup, I explicitly separated configuring of the details of
titles, names, etc. (the stuff that macros do), from consideration of
order and inter-macro punctuation. Is there some reason that approach
isn’t realistic? Precedent here is of course the makebst utility from
the BibTeX world.

Bruce

I probably spoke too soon; will wait until we can see the wireframes
to get a better sense of exactly what Victor’s suggesting here.

Hi Bruce (and everyone),

I’ve now formatted the text and uploaded the wireframes/mock-ups:
http://bitbucket.org/bdarcus/makecsl/wiki/UIProposal

If desired, I can also upload the original Photoshop file somewhere.

Looking forward to your comments!

Best,
Victor

Hi Bruce (and everyone),

I’ve now formatted the text and uploaded the wireframes/mock-ups:
http://bitbucket.org/bdarcus/makecsl/wiki/UIProposal

If desired, I can also upload the original Photoshop file somewhere.

Looks good to me now in the sense that it clearly communicates the ideas.

Looking forward to your comments!

A few quick ones on the wireframes.Will take a closer look later.

  1. per previous post, I don’t like privileging types as you do. I
    believe this ultimately makes things more complex all around,including
    for style creators.

  2. the “based on” stuff for dependent styles seems good on first look

  3. will think more on the token editing panes; much to consider

  4. on the last wireframe, I think based on previous discussions here
    with Rick, it would make sense to simply have a single link to
    install. That link would serve the serve with appropriate mime-type,
    which would be bound to a particular application. Each application
    should allow the path to the CSL directory to be configured, such that
    it’s feasible to use the same styles in different applications.

In any case, thanks for doing this Victor. It provides good food for thought.

Bruce

Thanks!

  1. per previous post, I don’t like privileging types as you do. I

believe this ultimately makes things more complex all around,including
for style creators.

To be honest, I didn’t quite understand your previous point - how else would
you do it? To me, this seemed the most logical progression: 1) Select style
to format, 2) within style, select document type to format, 3) within
document type, select metadata field to format.

If there’s an easier/less complex way, of course that would be great!

  1. on the last wireframe, I think based on previous discussions here

with Rick, it would make sense to simply have a single link to
install. That link would serve the serve with appropriate mime-type,
which would be bound to a particular application. Each application
should allow the path to the CSL directory to be configured, such that
it’s feasible to use the same styles in different applications.

Sounds like a good idea.

Best,
Victor

Thanks!

  1. per previous post, I don’t like privileging types as you do. I
    believe this ultimately makes things more complex all around,including
    for style creators.

To be honest, I didn’t quite understand your previous point - how else would
you do it? To me, this seemed the most logical progression: 1) Select style
to format, 2) within style, select document type to format, 3) within
document type, select metadata field to format.

If there’s an easier/less complex way, of course that would be great!

We do think about and discuss citations in terms of document types.
It’s often the first piece of information offered by the user when a
problem crops up: “I’m trying to cite a musical work …” At the same
time, though (and this is Bruce’s concern, I think), this could lead
to lots of replication, both in the CSL code, and in the operations
needed to define a complete style. The output style code would end up
being wrapped like this, presumably:

... ... ..

If the style editor assumes that those categories will be imposed at
the top level, it may not play well with existing styles in the
repository.

I think you can retain and leverage the habit of thinking in terms of
document types, while relying more heavily on CSL’s macro
capabilities, if by default you discriminate between document types
using a set of hard-wired assumptions about always-present, optional,
and always-absent variables for each type. If in a types-editing
screen, the user is given a “custom formatting” toggle against each
"type", the rest of the interface could look and work much as it does
in the current wireframes. The difference would be that, for the
generic “type”, all variables would be available, and the preview
would include labeled entries for each of the non-custom types. There
would need to be some state-change logic in the UI (what happens to a
custom def if a user goes back and unticks the "custom formatting"
toggle against a type, for example). But I’m pretty sure it would get
you net click savings.

As Bruce says, lots to comment on. I’ll stop here, also with thanks
to Victor for putting this up. It’s great to see this unfolding.

Frank

I’ll let Fred Gibbs weigh in on this, but at first glance I don’t see
how these mockups differ substantially from the JS-based tool that
Fred developed over six months ago. Before migrating that tool to
something more web-based, the exact same questions arose regarding the
tradeoff between a macro-based solution and an item-type-centric
solution. So perhaps Victor you could clarify exactly how what you’re
proposing diverges from Fred’s admittedly rudimentary yet actually
functioning solution? I think that would save us all a lot of time and
would avoid reinventing the wheel. Moreover, from the perspective of
software development, a working proof-of-concept seems like a better
place to start than mockups, particularly since the important
usability issues are completely independent of the underlying
programming language.

Sean Takats
Assistant Professor of History
Director of Research Projects
Center for History and New Media, George Mason University
@Sean_Takats | http://chnm.gmu.edu | 703 993 927

I’ll let Fred Gibbs weigh in on this, but at first glance I don’t see
how these mockups differ substantially from the JS-based tool that
Fred developed over six months ago. Before migrating that tool to
something more web-based, the exact same questions arose regarding the
tradeoff between a macro-based solution and an item-type-centric
solution. So perhaps Victor you could clarify exactly how what you’re
proposing diverges from Fred’s admittedly rudimentary yet actually
functioning solution? I think that would save us all a lot of time and
would avoid reinventing the wheel.

Will let Victor answer this, but wouldn’t be surprised if he wasn’t
aware of Fred’s earlier work.

Moreover, from the perspective of
software development, a working proof-of-concept seems like a better
place to start than mockups, particularly since the important
usability issues are completely independent of the underlying
programming language.

This (running code wo wider design discussion vs. wireframes, etc) is
a debatable point. Exactly what specific approach would you prefer
Mendeley (or anyone else interested in this project) take here?

Bruce

Hello,

Thanks!

  1. per previous post, I don’t like privileging types as you do. I
    believe this ultimately makes things more complex all around,including
    for style creators.

To be honest, I didn’t quite understand your previous point - how else would
you do it? To me, this seemed the most logical progression: 1) Select style
to format, 2) within style, select document type to format, 3) within
document type, select metadata field to format.

If there’s an easier/less complex way, of course that would be great!

We do think about and discuss citations in terms of document types.
It’s often the first piece of information offered by the user when a
problem crops up: “I’m trying to cite a musical work …” At the same
time, though (and this is Bruce’s concern, I think), this could lead
to lots of replication, both in the CSL code, and in the operations
needed to define a complete style. The output style code would end up
being wrapped like this, presumably:

I think that Victor is not familiar with the internal CSL structure,
so his approach is from the user point of view. In my opinion to think
as a user is a good start to design software that users will use. Of
course can be improved and guided a bit to generate better and more
generic CSL files instead of specific ones. Sometimes as a system
designer is easy to make the UI like a graphic representation of what
the system internals is… when sometimes is not the best way.2009/10/30 Frank Bennett <@Frank_Bennett>:

Let’s not be pedantic please. My argument against types is not about
putting the internal design cart before the horse; the internal design
reflects my belief about how styles work.

It’s also inspired by the commandline tool makebst, which I think
proves it’s possible to present a more generic, higher-level, UI.

I think, to tie some of this together, we probably ought to create a
separate wiki page (which I’ll do if I can find time) on the specific
design issue here, with maybe a couple of screenshots from Fred’s
work, and excerpts from our previous listserv discussions on this.

Bruce

In any case, I strongly suggest that people who have not yet done so
read through this thread (don’t want to have to repeat myself), and
try to take a look at Fred’s prototype.

http://n2.nabble.com/CSL-editor-tp2618606p2618606.html

Bruce

Hi all,

indeed I wasn’t aware of Fred’s work. If what I’m proposing already exists -
all the better. I must admit that I’m not able to fully appreciate the
discussion, because (as Carles points out) I have literally zero programming
knowledge, much less of the inner workings of CSL. Hence, I wasn’t even able
to try Fred’s prototype - I’ll have Carles show it to me in the office next
week.

So my entire contribution is just from a UI and user perspective. Ideally, I
believe UI mockups and user experience should be agreed upon first, and then
it should be decided how to best achieve this technically (and from reading
the thread, it’s apparent to me that Fred also had specific ideas about the
UI/UX in mind before he started coding).

Regarding Sean’s question as to how my proposal differs from Fred’s, I can’t
really tell without having tried the prototype. Generally though, I think
it’s important to have a browser-independent web app, and it should work
whether or not you have Mendeley or Zotero installed.

My hope in writing up the spec was to solicit feedback in order to come to
an agreement about the UI. Once we have reached this agreement, Mendeley
would like to commit developer time to build the web app - ideally getting
started within the next few weeks, and having a working version up on
www.citationstyles.org within the next 2-3 months. If Fred’s code can be
reused to speed up development, wonderful!

All the best,
Victor

Hi all,

indeed I wasn’t aware of Fred’s work. If what I’m proposing already exists -
all the better. I must admit that I’m not able to fully appreciate the
discussion, because (as Carles points out) I have literally zero programming
knowledge, much less of the inner workings of CSL. Hence, I wasn’t even able
to try Fred’s prototype - I’ll have Carles show it to me in the office next
week.

So my entire contribution is just from a UI and user perspective. Ideally, I
believe UI mockups and user experience should be agreed upon first, and then
it should be decided how to best achieve this technically (and from reading
the thread, it’s apparent to me that Fred also had specific ideas about the
UI/UX in mind before he started coding).

Regarding Sean’s question as to how my proposal differs from Fred’s, I can’t
really tell without having tried the prototype. Generally though, I think
it’s important to have a browser-independent web app, and it should work
whether or not you have Mendeley or Zotero installed.

My hope in writing up the spec was to solicit feedback in order to come to
an agreement about the UI. Once we have reached this agreement, Mendeley
would like to commit developer time to build the web app - ideally getting
started within the next few weeks, and having a working version up on
www.citationstyles.org within the next 2-3 months. If Fred’s code can be
reused to speed up development, wonderful!

Here are some thoughts to follow on from Bruce’s views about reduced
reliance on defining per-type formats at the top level.

I think that the possibility of per-type formatting needs to be in
there. Some styles do need this, and it doesn’t always make sense to
push the conditional into a macro. But there are big gains from
emphasizing macros in the design, I think.

There is a great deal of complexity lurking in the five main rendering
nodes of CSL (names, date, number, text). I may be overly impressed
with what we have added and refined for CSL 1.0 over the past few
months, but I wonder whether it is really feasible to get a usable
tool together that covers all of the possibilities and produces valid
CSL files in 2-3 months’ time. But with an approach that starts off
macro-centric, most of the detail can be dropped on the floor for the
time being, without losing the benefits of a WYSIWYG interface.

The repository contains quite a few styles already, most of which are
built out of macros. There is also a small but active population of
style authors skilled in crafting macros by hand. One option would be
to initially forego any attempt at all to support sub-element
formatting of the five main rendering elements in the gui, but instead
rely entirely on macros to supply them, and assume that new
hand-crafted macros will be added to the library on demand as the need
arises.

This would largely eliminate the need to express conditional branching
in the gui, which is a difficult problem not addressed by proposals so
far (I think – I haven’t yet run Fred’s tool). Two forms of
branching cannot be completely pushed into macros: that for residual
item-type formatting; and that needed for first-ibid-subsequent
formatting. It would also leave – and throw the focus on – another
condition-related issue that (I think?) has also not yet been
addressed: the use of grouping (with an intra-group delimiter and a
group-wise prefix and suffix). Grouping is an essential feature of
styling logic, and although it’s not immediately obvious how best to
express it in a gui, it’s probably an issue worth focusing on pretty
closely.

If you went this route, the first step (before deployment of CSL 1.0?)
would be to set up for automated repository housecleaning, identifying
macros that have exactly the same CSL definition, giving them uniform
names, and extracting them to a WYSIWYG library archive that can be
updated automatically from the raw contents of the repository. Some
means of automatically assigning descriptive names to macros would
need to accompany that, to provide consistent and meaningful names
without human intervention.

Once you had the workflow set up, basically everyone would continue
working as they do currently, but with the WYSIWYG environment
benefiting incidentally from tweaks and extensions introduced to style
macros the archive, either by style authors working in the Old Way, or
by macros supplied on request to WYSIWYG-reliant authors.

As Bruce suggests, element-level formatting options on the five main
elements could be introduced into the gui according to need. But in
the first cut, you might treat it as a distraction, and leave it out
completely, in order to focus on the attributes of group, layout,
sort+key and a few items on the top-level style node.

Frank Bennett

Hi all,

indeed I wasn’t aware of Fred’s work. If what I’m proposing already exists -
all the better. I must admit that I’m not able to fully appreciate the
discussion, because (as Carles points out) I have literally zero programming
knowledge, much less of the inner workings of CSL. Hence, I wasn’t even able
to try Fred’s prototype - I’ll have Carles show it to me in the office next
week.

So my entire contribution is just from a UI and user perspective. Ideally, I
believe UI mockups and user experience should be agreed upon first, and then
it should be decided how to best achieve this technically (and from reading
the thread, it’s apparent to me that Fred also had specific ideas about the
UI/UX in mind before he started coding).

Regarding Sean’s question as to how my proposal differs from Fred’s, I can’t
really tell without having tried the prototype. Generally though, I think
it’s important to have a browser-independent web app, and it should work
whether or not you have Mendeley or Zotero installed.

My hope in writing up the spec was to solicit feedback in order to come to
an agreement about the UI. Once we have reached this agreement, Mendeley
would like to commit developer time to build the web app - ideally getting
started within the next few weeks, and having a working version up on
www.citationstyles.org within the next 2-3 months. If Fred’s code can be
reused to speed up development, wonderful!

Here are some thoughts to follow on from Bruce’s views about reduced
reliance on defining per-type formats at the top level.

I think that the possibility of per-type formatting needs to be in
there. Some styles do need this, and it doesn’t always make sense to
push the conditional into a macro. But there are big gains from
emphasizing macros in the design, I think.

There is a great deal of complexity lurking in the five main rendering
nodes of CSL (names, date, number, text). I may be overly impressed
with what we have added and refined for CSL 1.0 over the past few
months, but I wonder whether it is really feasible to get a usable
tool together that covers all of the possibilities and produces valid
CSL files in 2-3 months’ time. But with an approach that starts off
macro-centric, most of the detail can be dropped on the floor for the
time being, without losing the benefits of a WYSIWYG interface.

The repository contains quite a few styles already, most of which are
built out of macros. There is also a small but active population of
style authors skilled in crafting macros by hand. One option would be
to initially forego any attempt at all to support sub-element
formatting of the five main rendering elements in the gui, but instead
rely entirely on macros to supply them, and assume that new
hand-crafted macros will be added to the library on demand as the need
arises.

This would largely eliminate the need to express conditional branching
in the gui, which is a difficult problem not addressed by proposals so
far (I think – I haven’t yet run Fred’s tool). Two forms of
branching cannot be completely pushed into macros: that for residual
item-type formatting; and that needed for first-ibid-subsequent
formatting. It would also leave – and throw the focus on – another
condition-related issue that (I think?) has also not yet been
addressed: the use of grouping (with an intra-group delimiter and a
group-wise prefix and suffix). Grouping is an essential feature of
styling logic, and although it’s not immediately obvious how best to
express it in a gui, it’s probably an issue worth focusing on pretty
closely.

If you went this route, the first step (before deployment of CSL 1.0?)
would be to set up for automated repository housecleaning, identifying
macros that have exactly the same CSL definition, giving them uniform
names, and extracting them to a WYSIWYG library archive that can be
updated automatically from the raw contents of the repository. Some
means of automatically assigning descriptive names to macros would
need to accompany that, to provide consistent and meaningful names
without human intervention.

Once you had the workflow set up, basically everyone would continue
working as they do currently, but with the WYSIWYG environment
benefiting incidentally from tweaks and extensions introduced to style
macros the archive, either by style authors working in the Old Way, or
by macros supplied on request to WYSIWYG-reliant authors.

As Bruce suggests, element-level formatting options on the five main
elements could be introduced into the gui according to need. But in
the first cut, you might treat it as a distraction, and leave it out
completely, in order to focus on the attributes of group, layout,
sort+key and a few items on the top-level style node.

Just realized that it was a simple thing to install Fred’s work, so I
took a look. It does provide for grouping – and nested grouping –
which is really great.

(The fact that general conditions are not supported kind of confirms
the thought that it would be insanity to try.)

Something with grouping support like Fred’s interface, but with simple
drag-and-drop for selecting off-the-shelf macros instead of the CSL
primitives (each with its own frightening array of options), might be
just the ticket. The challenge then would be to guide users to the
correct macro with efficient search and description support – but
you’re going to have that problem in any case. Maybe use per-feature
icons, like a travel guide, with color-coding for some of the more
abstract characteristics?

Frank

I (and I think Rick) have suggested this in the past, but rather than
having users search for macros manually, it might be possible to simply
have the user format a standard reference as it would appear in their
desired style—which I image would be what a user would prefer/expect to
do—and have the tool search through pregenerated HTML output for
available macros that produced the same output. TinyMCE (or similar)
would need to be configured such that it only produced equivalent markup
to citeproc-js for any given visual presentation, and any
elements/attributes in the pregenerated output that didn’t affect
formatting would need to be stripped.