NewsLetter November Ideas about www HOT 4 CLOSED

Style guides (thanks to @Bradamant3):

Style guides -- discussion October 5-6
Began with question about "Webpage" or "web page" from someone just embarking on creating style guide and wondering how to resolve such issues "I've previously hit up google and just looked at which is most common"

Folks suggested the following resources:

• Merriam-Webster
• (Poll the Docs says that of 100 respondents, most at all sizes of teams use an in-house style guide; only other style guide mentioned was Chicago Manual of Style)
• 18F (https://pages.18f.gov/content-guide/)
• MailChimp (http://styleguide.mailchimp.com/)

Recommendation to pick one authoritative style guide and stick to it, with caveat that "Chicago and other non-tech style guides are going to lag behind usage"

Considerable lament over the passing of techcomm-specific style guides, especially Microsoft Manual of Style for Technical Publications (MSTP). Mention also of Yahoo style guide.

Interest in open source style guide (with linters to support), but concern also over "holy wars"

Related but not directly part of last week's discussion: considerable interest in Thursday Bram and Audrey Eschwright's Responsible Communication kickstarter, and also in Thursday's style guide template which she generously has shared for the world: http://www.thursdaybram.com/download-my-in-house-style-guide-template-to-use-however-you-want

Also noted: there's a forum discussion from last year about style guides, with more suggestions: http://forum.writethedocs.org/t/style-guides-for-documentarians/112

from www.

Acronyms, a la Hillary:

Abbreviations and Acronyms: This discussion happened 10/7/16 through 10/10/16.

A quick poll about abbreviating "input/output" turned into a broader discussion about abbreviations in general. These were the central points:

• For common abbreviations and acronyms, are definitions necessary? The consensus on this point seemed to be yes, a definition is needed even for common abbreviations and acronyms. Folks leaned away from assuming that your readers are familiar with terminology and abbreviations. "Assumption is the mother of all feckups," as one participant put it! Basically, you never know who is reading your docs, so it's dangerous to assume that every reader will understand undefined abbreviations and acronyms.
• Does the intended audience affect whether you define abbreviations and acronyms? Maybe you've heard something like "anyone ready to look at [this] documentation would already know what [X] means." Folks seemed to agree that even if you think the audience knows what you do and understands the terminology, it's a mistake to disregard the readers who are new to the field or aren't as familiar.
  • One recommendation was covering basic concepts and abbreviations in a "Getting Started" section, as well as in marketing materials, to help make sure that readers have a certain level of familiarity before they dig in to your documentation. In a similar vein, another person talked about using lists of prerequisite information so readers can check their knowledge before jumping into a doc set. These strategies can help when you have to write documents that are friendly to newcomers and useful to experienced readers.
  • One person mentioned maintaining two streams of docs: one for technical readers and one for non-technical readers.
• Can you count on readers to find definitions for acronyms via web searches? It's easy enough to search for unfamiliar acronyms, but what if an acronym has more than one meaning? If you don't define what the acronym means in your docs, readers may settle on a different meaning based on their searches. Take "CI" as an example. The most likely meaning might be "continuous integration," but there are more than 200 possible meanings…and TheFreeDictionary.com's list of the most common meanings doesn't include "continuous integration" at all!
• What does "define at first use" mean these days? With so many technical documents published online, you might need to rethink the rule about defining acronyms at first use. Defining once "per document" doesn't make much sense when the document isn't a printed manual, there's no "beginning" to flip back to, and there's no index to check. Recommendations included spelling out acronyms at their first use in each section of documentation or in the overviews for sets of functions. The takeaway was that document structure and format will determine the best way to define acronyms.

The discussion also included the possibility of discouraging people from your product if they don't have the necessary level of familiarity to use it. People who don't understand your docs may be less likely to buy your product. At the same time, companies may prefer to focus technical writing resources on helping customers who can use the product instead of marketing to or educating potential users.

Interestingly, some folks mentioned that the "everyone knows THAT" perspective can tie into knowledge gaps like the location of Punt and phenomenon like iconography that doesn't make sense anymore.

For another take on how audience can affect your documentation decisions, check out https://jacobian.org/writing/what-to-write.

Oh, and if you're curious, the Slack channel poll found that folks use "I/O" more often than "IO" as the abbreviation for "input/output"—at last count, "I/O" had 18 votes and "IO" had 3 votes.

from www.

have a look at the doc tooling/CMS conversation from October 4, too: https://writethedocs.slack.com/archives/general/p1475524991001038

from www.

We should include a link to Docs Down Under -- https://linux.conf.au/schedule/presentation/3/ -- a good example of a “docs event at a dev event” type thing. Can mostly just talk about it, and mention the CFP if you're going to LCA (or on the off chance you live in Hobart :))

from www.