Create a section on topic-based authoring

[ghost]

I was skimming a bit through issue asciidoctor/asciidoctor#626 and suddenly Dan’s comments (this and this) blew my mind. I never heard about topic-based authoring before, but it seems to me that it’s something everybody writing for the web should know about.
It could go in the "best practices" document.

[ghost]

Most information on the net is about DITA and xml, so there’s definetely space for asciidoc-oriented material.
Also I found this article that’s fairly interesting.

[jaredmorgs]

I'm doing a topic based authoring solution with AsciiDoc at the moment to
create embedded help for an interface without any help system at all.

Without the ease of Asciidoctor and includes it would be impossible.

Unfortunately it is on proprietary, closed software. The concepts I'm using
however, are neither closed or proprietary.

On Sat, Apr 9, 2016, 00:03 andya9 notifications@github.com wrote:

Most information on the net is about DITA and xml, so there’s definetely
space for asciidoc-oriented material.
Also I found this article
http://idratherbewriting.com/2012/07/31/misconceptions-about-topic-based-authoring/
that’s fairly interesting.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
#569 (comment)

Sent from Mobile.

[mojavelinux]

This is definitely a pattern we should explore in the user manual.

@andya9 that article is a nice find! Thanks for sharing.

From that article:

If the help content were more readable and engaging, following a clear narrative flow, I bet more users would actually read the manual.

I totally agree. A narrative flow is paramount. It's something the Asciidoctor user manual is lacking at the moment, but certainly a good goal.

If I approached technical instruction as a series of articles, which fit together coherently, somewhat like on a blog, I would do a much better job.

💯 I think this is exactly what we need for the Asciidoctor site. We need to develop a progression from one topic to the next, advancing the reader along a learning path.

[ghost]

1. narrative flow and engaging content: really really important, but also really really difficult when writing docs 👅 I think that we will be forced to keep some content in a dry "reference card", for example the explanation on what each attribute does. But for the explanation of the syntax it could be doable; some more points IMO we should keep in mind: keep it concise (but not dry); rely on (possibly funny and meaningful) examples more than explanations.
2. blog-like structure: this is a really exciting idea, and should be straightforward to implement; an article for em-strong and so on, one for admonitions, one on macros, one on asciidoc’s background among markup languages, and so on.

[mojavelinux]

blog-like structure:

This is basically the approach that Mr. Haki took with Awesome Asciidoctor. (http://mrhaki.blogspot.com/search/label/Awesome%3AAsciidoctor) If we were to follow that strategy, we'd probably focus on more mainstream topics rather than clever finds and undocumented behavior, though.

[ghost]

For that, we could have an article on "tips".
Anyway, as blog-like I meant something based on independent articles, but without the cruft of dates and with a sorted index.

[mojavelinux]

Yep, I get your point.

[toraritte]

This is a fairly old issue (and I am just starting out with AsciiDoc & DocBook), but couldn't assemblies be used with AsciiDoc? The latest iteration of the DocBook 5.2: The Definitive Guide (Version 5.2.6 for DocBook 5.2b09a) has a chapter called Chapter 6. DocBook Assemblies which is explicitly about topic-oriented authoring, and my understanding is that AsciiDoc is DocBook under the hood (apologies for my ignorance if I misinterpreted something). Based on the timestamps, this seems to have been added way after 2016.

(Just mentioning here that when it comes to topic-based authoring, DITA seems to be the de-facto standard, also implicitly mentioned in the cited chapter above, yet I never heard of it...)

update: It seems that this is already a thing: Creating Strimzi documentation assemblies.