The ‘So What?’ Question

Continuing my previous post on editing, here are some useful tips for writing stronger papers provided by Theresea MacPhail, a digital editor for a science journal.

I’d like you to pause a moment from your daily diligence — grinding out future articles and book chapters — and think about those of us who work as editors and manuscript reviewers. And I’d like to ask a big favor — one that will benefit us and you. Before you send in that manuscript, take a second look at that draft you’ve polished three or four times and ask yourself the following question: What is my main argument here?

Theresa MacPhail goes to suggest three signs that you do not have a central argument:

  • You can’t answer the “So what?” question.
  • Your introduction and conclusion don’t mesh.
  • Your colleagues can’t explain your main argument.

The last point is important. Having a colleague explain your main argument can go a long way in exposing your blindspots and strengthening your argument. Another benefit in having a colleague (or family member or friend) read your paper is to assist in ‘polishing up’ the text. A paper that is poorly written has greater risk in being rejected outright.

Source: The ‘So What?’ Question | ChronicleVitae

Should Journals Be Responsible for Reproducibility?

As the incoming editor of College & Undergraduate Libraries, I find myself asking similar questions regarding many of the papers that I edit. The editors of the American Journal of Political Science outlines their concerns in this article in Inside Higher Education. 

Our goal is to establish a standard for the information that must be made available about the research that appears in our journal. By requiring scholars to provide access to their data and conducting our own replications on those data, we confirm the rigor of, and promote public confidence in, the studies we publish. As one of the top journals in the discipline, we hope to create state-of-the-art standards that others in the field will aim to adopt.

The editors discuss their expereinces and offer suggestions for those journals interested in pursuing reproducibility and  transparency.

Source: Should Journals Be Responsible for Reproducibility? | Rethinking Research

A Survey of Digital Humanities Programs

Chris Alen Sula, S. E. Hackney, and Phillip Cunningham provide the results of a survey they did on examining the DH activities that constitute these programs,  the skills and methods needed, and what is missing. The value of this survey is that it provides “some empirical perspective on debates about teaching DH, particularly the attention paid to theory and critical reflection.”

“The number of digital humanities programs has risen steadily since 2008, adding capacity to the field. But what kind of capacity, and in what areas? This paper presents a survey of DH programs in the Anglophone world (Australia, Canada, Ireland, the United Kingdom, and the United States), including degrees, certificates, and formalized minors, concentrations, and specializations. By analyzing the location, structure, and disciplinarity of these programs, we examine the larger picture of DH, at least insofar as it is represented to prospective students and cultivated through required coursework.”

Source: A Survey of Digital Humanities Programs

XML oXygen Editor Users Meetup

I was in Rockville, Maryland on May 5th for an all day meeting of the DC area oXygen XML Editor users. Hosted by George Bina and Radu Coravu, who outlined the new features in oXygen version 19 released last month.  This meeting was special in that it doesn’t happen every year so I availed myself of an interesting opportunity.

Many Improvements to DITA

DITA reusable components view, insert DITA Key References

FullSizeRender (2)

Improvements included converting DITA to PDF using CSS, DocBook 5.1 schema updates and stylesheets, and Markdown, XSLT improvements with Saxon 9.7.0.15, convert between multiple xsl:if and xsl:choose, using partial XPath paths to create new code and templates, and other refactoring features. Many of the improvements are designed to speed up workflow. TEI Schemas 3.1.0 were updated. Web Author improvements including CMS connectivity.

User Assistance with Schematron

Schematron is a ISO standard (ISO/IEC 19757)–DSDL (Document Schema Definition Language); a very simple schema language less than 10 elements and 20 elements in total; a different kind of schema–defines business rules, not the document structure, the error messages are specified inside the schema. XPath uses Schematron to match and assert; XSLT to extend XSLT based Schematron implementations; and SQF provides quick-fixes to identified issues defined as small scripts annotating the Schematron assertions. Schematron can help you in the authoring phase of a project instead of review time, publishing time, and production time. Identify and fix the problems as early as possible, says George!   Intelligence style guide project for Dynamic Information Model;  https://github.com/dim

Some rules:

FullSizeRender (2)

Learn DITA from a Markdown perspective
Markdown is  a text-to-HTML conversion tool for web writers. Markdown recognizes Markdown fragments in DITA topics and convert them automatically to DITA markup. the code is on GitHub: https://github.com/oxygenxml/ditamark. Recognized Markdown patterns include lists, quotes, links, images, tables, and titles.

Schematron Quickfix with SQF can be found here: https://github.com/schematron-quickfix/sqf.  SQF is a simple language to use (only 4 actions!).

Changing  XML with XSLT and XQuery

Implement Author actions and refactoring options

XML refactoring actions allow making repetitive structural changes in XML documents based on specific use cases.

Lightning Talks

There were some short presentations on oXygen XML editor features and applications.

oXygen for training sessions

JATS Support in Oxygen XML Editor

Wendell Piez from Piez Consulting Services provided an overview of JATS support. A wiki is available: http://jatswiki.org/wiki/Tools#JATS_Framework_for_oXygen_XML_Editor .

Testing XSLT

XSpec is a unit test and Behaviour Driven Development (BDD) framework for XSLT and XQuery. https://github.com/xspec/xspec/wiki

Code is available at GitHub: https://github.com/xspec/xspec

Three common ways for testing XSLT: matching scenarios,  named scenarios, and function scenarios.

Discover the Author mode

For development XML based languages like:

Making XML Editable on the Web

XAAS –XML Authoring as Service

oXygen XML Web Author = A REST service to interact with XML content!

Parameters

  •  URL –pointing to the file to edit
  • ditamap — pointing to a DITA map for editing context
  • … — more parameters are available

Integration is key

The web XML editor DOES NOT EQUAL opening XML to edit in browser. The real power of a web editor can be seen when it is integrated into your workflow.

IMG_4726

xproc.org and exproc.org are similar services (GitHub, Travis).

Integration is the key for web XML authoring!

Discover the oXygen Collaboration Platform

Why oXygen Content Fusion?

You need to:

  • collaborate
  • have access to specific tools
  • work within a specific workflow
  • access a repository
  • approve changes before reaching the repository
  • have a less formal way of receiving feedback.

Content Fusion allows you to create a review/collaboration task, share tasks URL with your contributors, and get changes back . There is a Content Fusion Connector plugin for oXygen as well.

Using Saxon JS

Wendell Piez gave a presentation on using Saxon JS.

Future Plans

George Bina outlined future plans for oXygen. The summary can be found here: https://www.oxygenxml.com/events/2017/futurePlans.pdf