AsciiDoctor's content strategy

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

AsciiDoctor's content strategy

mojavelinux
Administrator
This post was updated on .
To better understand the vision behind Asciidoctor--to promote the creation of reusable, human-readable, semantic content--I strongly encourage you to watch the following talk:

Adapting Ourselves to Adaptive Content
http://aneventapart.com/news/post/aea-video-karen-mcgrane-adapting-ourselves-to-adaptive-content

This talk is given by one of the leading thinkers on Content Strategy, Karen McGrane. She reminds us that the days of the single channel (read as "device") for delivering content (spanning news to documentation) have passed. Separating content from presentation, and weaving meaning into that content with metadata, is more essential than ever before.

As a content creator, you are faced with a choice. You can either write and design for a single device (e.g., print, desktop web, mobile) and watch your content get chopped up, recycled and watered down to fit other devices (Conde Naste), or you can invest a little extra time up front to write semantic, chunked content that isn't coupled to the presentation and watch your content flourish (NPR).

DocBook and AsciiDoc are both containers for semantic, structured content. Where DocBook falls short is that it's not human readable (not even close). AsciiDoc stands above DocBook because it's actually usable (and mergable and pull-requestable). AsciiDoc stands above other markup languages because it maintains a clean separation of content (not some messy plain-text, HTML hybrid like Markdown).

Storing your content in AsciiDoc is more than just an easier way to write documentation. It maximizes the *value* of your content. The lessons in this video will help us evolve Asciidoctor so we can inject even more value into the content.

I want to thank Sarah White for introducing me to this video and the field of Content Strategy. Heed her wisdom and go watch it!

-Dan

--
Dan Allen | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: AsciiDoctor's content strategy

mojavelinux
Administrator
This post was updated on .
I want to also add that one of the most brilliant, forward-thinking features of AsciiDoc is the block role (or style). This feature, which is only seen in one other lightweight markup language (reStructuredText), enables you to identify paragraphs or blocks of content for use in different contexts.

For example, to define an abstract:

[abstract]
A chunk of content that can be used where the abstract of the content needs to be displayed.

The abstract is a built-in role (called a style). When a built-in role is not available, a role can be used to pass the same type of information:

[role="feature-list"]
* lightweight
* reusable
* readable
* etc...

And not only can a role be assigned to a single paragraph, block or list, it can also be assigned to a sequence of content thanks to the open block.

[role="lead"]
--
Opening paragraph of the lead.

Another lead paragraph.

* topic 1
* topic 2
* topic 3

Conclusion of the lead.
--

This allows AsciiDoc to fully satisfy the requirements of journalism. It could absolutely be used as *the* storage format for content submissions to any news organization, (true) CMS or even a call for papers.

-Dan
Reply | Threaded
Open this post in threaded view
|

Re: AsciiDoctor's content strategy

mojavelinux
Administrator
One example of where content chunking is used already in AsciiDoc is in the man page structure (and backend).

Here's a snippet of a man page (from the git project):

= git-cherry-pick(1)

== NAME
git-cherry-pick - Apply the changes introduced by some existing commits

== SYNOPSIS
[verse]
'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] <commit>...
'git cherry-pick' --continue
'git cherry-pick' --quit
'git cherry-pick' --abort

== DESCRIPTION

Given one or more existing commits, apply the change each one
introduces, recording a new commit for each.  This requires your
working tree to be clean (no modifications from the HEAD commit).

== OPTIONS
<commit>...:: Commits to cherry-pick.

In this case, the section title names are doubling as the role (which is fine, AsciiDoc is flexible that way). Suffice to say, the name, summary, description, etc can be extracted out of this structure cleanly. This chunking is precisely what Karen is talking about in her presentation.
Reply | Threaded
Open this post in threaded view
|

Re: AsciiDoctor's content strategy

RainerB
The link to the talk is outdated, removing the "post/" behind "news/" makes it work:
http://aneventapart.com/news/aea-video-karen-mcgrane-adapting-ourselves-to-adaptive-content
https://discuss.asciidoctor.org/AsciiDoctor-s-content-strategy-td237.html
discuss.asciidoctor.org
crawl=CC-MAIN-2019-39
59369
application/http; msgtype=response
sha1:JMSPD726N7ALXO53MGYDVEQ4VKY4EDAE
<urn:uuid:6d657406-3301-40a7-9736-6dcec432e150>
2019-09-20T12:48:11Z
162.255.23.37
text/html
sha1:32P5UYOVWD3M3YDK4F5AMSXURIOUWMGN
<urn:uuid:078ca341-f086-4960-b701-1412ad7deb00>
https://discuss.asciidoctor.org/AsciiDoctor-s-content-strategy-td237.html
response
<urn:uuid:654bc04e-acab-417d-9563-b14305ed8f23>
isPartOf: CC-MAIN-2019-39
publisher: Common Crawl
description: Wide crawl of the web for September 2019
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-67-67-151.ec2.internal
software: Apache Nutch 1.15 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 1.1-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: http://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/