Style Requirements and How to Meet Them

[orcmid]

There are varieties of style requirements that arise when creating words, in the open or not. Some have to do with the words. Some have to do with required structure and format of draft submissions and final forms.

These are factors in how one might employ docEng patterns on the GitHub platform. What ones are used? And how does one navigate requirements that are imposed.

This might be far more than one expects of docEng. At the same time, this is something that has to be faced. Let's discuss.

[orcmid]

Here is an example of style requirement for submission of a technical paper to a scientific conference.

https://lrec2020.lrec-conf.org/en/submission2020/authors-kit/

There are strong requirements and three templates are provided. The ISA-17 call for papers strongly recommends the LaTeX template.

The TL;DR: What other style cases and requirements are you aware of?

Observations

MiKTeX is installed as a companion to pandoc on Windows, so the LaTeX template might be usable. It is clear that Markdown does not satisfy these conditions directly, and one must use one of Word, "OpenOffice" (their term)., or LaTeX. LaTeX is not exactly writer friendly, although it is very popular in academic and scientific circles.

To take full advantage of GitHub platform version control along with issues and projects, some form of Markdown may also enter the picture. One could use LaTeX similarly, since it employs a plaintext format. It is not clear to me that we need a Literate Publishing along with Literate Programming, but LaTeX does provide satisfiers for both notions.

[orcmid]

I had put this book in the stack to go to Goodwill. It is dated, and I don't know where there might be an on-line and more-current version.

Microsoft Corporation.

_Manual of Style for Technical Publications_, ed.2. Microsoft Press (Redmond, WA: 1998). index and CD-ROM included. ISBN 1-57231-890-2.

The CD-ROM also includes the Microsoft Press Computer Dictionary and the content is in searchable HTML. There is also a "traditional" Windows Help version of the manual.

[orcmid]

This book also listed other "standard reference works," where there are doubtless later editions.

• Chicago Manual of Style, ed. 14,. University of Chicago Press (Chicago: 1993)
• Harbrace College Handbook, ed. 12. Harcourt Brace College Publishers (Forth Worth: 1994).
• Windows Interface Guidelines for Software Design. Microsoft Press (Redmond, WA: 1995).

[orcmid]

There's also

• Microsoft Windows User Experience: Official Guidelines for User Interface Developers and Designers. Microsoft Press (Redmond, WA: 1999. ISBN 10-7356-0566-1.
• Schmitt, David A. International Programming for Microsoft Windows: Essential guidelines for globalizing and localizing your software. Microsoft Press (Redmond, WA: 2000). ISBN 1-57231-956-9. with CD-ROM.

I'm uncertain how pertinent this is for either Windows or general understanding. They are identified because I had them and they are the kind of thing that one should fine in developing technical publications and accompanying software tools under contemporary conditions.

At one time, there was specification of the Common User Arrangement (CUA), a component of IBM's 1987 specification for System Application Architecture (SAA) intended to apply across IBM product families, including the PC.

The familiar layout of two-dimensional ASCII terminal interface in MS-DOS applications was aligned with the CUA top-strip menu (File, ..., Help) and some general things about shortcut keys, etc. There are other uses.

Current equivalents to CUA may be valuable for the precision with which features of software and its technical/user documentation are organized and oriented.