Improve the docs page

[ggrossetie]

Get Started with Asciidoctor

In my opinion, the "Using Mac OS X?" is too big and draw too much attention in the "Get Started with Asciidoctor". Currently the Windows and Linux guides are mixed into one but I think it's better to have a dedicated guide for Windows. So one guide per OS would be great:

• How to install Asciidoctor on Windows
• How to install Asciidoctor on Linux
• How to install Asciidoctor on Mac OS X

The last three items of the "Get Started with Asciidoctor" should be move to the "Converters" section:

• Convert AsciiDoc to HTML5 including custom look and feel with Asciidoctor
• Convert AsciiDoc to deck.js presentation with Asciidoctor
• Convert AsciiDoc to reveal.js presentation with Asciidoctor

Integrations and Plugins

We are integrated with a lot of technologies and I think we could make the page more visual if we change the layout and add the logo of each technology (to look like https://spring.io/projects):

• Java
• Gradle
• Maven
• Javadoc
• JavaScript

[mojavelinux]

I completely agree. Several people have pointed out recently that this page lacks clarity. It's true. The page layout was temporary...but temporary has become long term :)

Let's keep discussing on this thread ways we can organize this page and try to arrive at some action items to get us there. cc: @graphitefriction

[graphitefriction]

I completely agree as well @Mogztter !

So to get all the docs in some sort of flow that is actually based on a user's reality (and therefore useful to them), we need to do two things in tangent.

1. Make a list of all of the parts of the Asciidoctor toolchain.
2. Make a list of the different types/stages of Asciidoctor users.

I started drafting up these lists here and then realized they were really freaking long...so instead, see this gist: https://gist.github.com/graphitefriction/6adff94aa85087e7890c

Comment, add, slash all you want 😊

[graphitefriction]

@Mogztter Crap, @mojavelinux just told me you can't issue pull requests to gists or directly edit them so I'm going to move the content from the gist to the wiki so that you can edit the doc directly. Sorry! I'll link to the wiki page when I'm done.

[graphitefriction]

Okay, let's try again 😊 Here's the wiki page: https://github.com/asciidoctor/asciidoctor.org/wiki/Docs-IA

[mojavelinux]

👍

[ggrossetie]

Woah, the list is quite impressive!

I think the main goal is to answer user's question "I want to...". Non exhaustive list:

• I want to learn the AsciiDoc syntax
• I want to remember the AsciiDoc syntax
• I want to try Asciidoctor
• I want to edit AsciiDoc like a pro
• I want to convert my AsciiDoc document to [pdf, EPUB, DocBook...]
• I want to use advanced syntax/extensions (diagram, chart, emoji, equations/stem)
• I want to integrate Asciidoctor in my toolchain (sbt, maven, gradle)
• I want to write extensions for Asciidoctor
• I want to contribute to Asciidoctor
• I want to integrate Asciidoctor in my [Java, Ruby, JavaScript, Groovy] project
• ...

The list of types of users is really good and make me think about the most "useful" page for all of them. I don't know if you have analytics on the asciidoctor.org website but I bet the common syntax is the top-viewed page ?
Some other documentations are only useful once, for instance installation guide, when you are done you don't need it anymore, but the common syntax is always useful IMHO.

I also think it's a good idea to have a "Quickstart" guide with "no install" at all for "Group 1". This guide can answer the question "I want to try Asciidoctor".

On a different topic, in the current page, the section "The Basics" is too "scary". I think it's better to let the user try before telling him "Why" or "Who" or "How A differ from B". Maybe it's my way of learning new technology but the first thing I want is to start using the technology, then enjoying it, then get stuck, then read the documentation 😄

I will think a little more on "types of users" before editing the wiki page 🎱

[graphitefriction]

This is fabulous info!

I love the questions and incorporated them into the wiki document. For the most "useful" page per user group, I like to also think in terms of "track". By track I mean a set of lessons, in order, that would help that user group accomplish their most common goal / need / usecase. A track can include numerous lessons (tutorials) which are easily consumable (i.e. not take longer than 10 minutes). By thinking in terms of a "track" it keeps me from adding information (docs, links, etc.) that I think might just be "nice" or "interesting". And then everything just gets messy!

Analytics: Yes, we do have them! @mojavelinux how do we get into the analytics console?

One-use docs: Yes! I like the idea of sorting things per 1 use versus always need docs. Once we identify 1 user vs infinite use we can come up with a visual hierarchy and linking strategy for these docs.

Which leads us to the chaos that is the current docs page. This page is typical of a project that went from new / um-we're-not-sure-what-we're-doing-yet structure to we've-got-lots-of-docs-for-lots-of-people-but-haven't-updated-our-structure-yet 😵

And I agree, the basics section is too scary 😖 and not really that relevant to someone who wants "to try asciidoctor"

I added a little more to the user groups on the wiki page.
I also started another page about the tracks / user group pages. It's really rough right now though.
https://github.com/asciidoctor/asciidoctor.org/wiki/Learning-Track-Outlines

[danielkocot]

@graphitefriction @mojavelinux Do you need any support in improving the docs page? At JavaLand I got in contact with asciidoctor. I used asciidoc in earlier days.

[ggrossetie]

Sorry I took some time to reply.
You summed up my thoughts with your idea of "track" :)

One other thing that come to my mind is that we need a way to visual identify or to sort the same "track" but in different "environments".

I think the play documentation is a good example of one way of doing it. There's the common part and the getting started part and then you can choose to enter the section "Play for Java developers" or "Play for Scala developers".

Asciidoctor is more than a developer tool so the term "developer" is maybe too restrictive but you get the idea.

I think we need something similar because depending on the environment the documentation will be different for the same goal. For example if I want to use extension in Ruby or in JavaScript or in Java, the setup will be completely different.

I saw on @mojavelinux's slides at Devoxx "Write in AsciiDoc, Publish Everywhere!" an illustration with bubbles. Maybe this kind of illustration could help to explain how things are related/linked:

Asciidoctor Core (Ruby) --- Asciidoctor.js (JavaScript impl) |--- Node.js
                                                             |--- Browser  |--- CMS --- HubPress.io
                                                                           |--- Chrome extension
                                                                           |--- Firefox add-on

That would also draw attention on how big is the ecosystem now!

[ggrossetie]

@danielgrycman Yes, the more support we can get the better 😄

[danielkocot]

@Mogztter @graphitefriction @mojavelinux What would be a good starting point to support you? 😄

[ggrossetie]

@danielgrycman I think you can start by writing down the questions you have about Asciidoctor: https://github.com/asciidoctor/asciidoctor.org/wiki/Docs-IA#questions-asciidoctor-users-have

[mojavelinux]

Analytics: Yes, we do have them! @mojavelinux how do we get into the analytics console?

We use Google Analytics. It doesn't provide a way to have a public view (which frustrates me), but @graphitefriction and @Mogztter should now have access. If others want read access, feel free to ask.

[mojavelinux]

I renamed the page to make it more clear. Not everyone knows what "IA" is :)

https://github.com/asciidoctor/asciidoctor.org/wiki/Docs-Information-Architecture

[mojavelinux]

I think we can take some inspiration from OpenShift's new documentation portal (based on Asciidoctor, of course). It presents one possible way to organize the numerous audiences we need to address.

http://docs.openshift.org/latest/welcome/index.html

Contrast that with their previous entry point, which looked a lot like our current docs page:

http://docs.openshift.org/origin-m4/index.html

[mojavelinux]

One place concrete to start is the extension writer's guide. How to write extensions is a question that frequently comes up. Addressing it not only will allow us to practice outlining a guide, it will also put some support cases to rest :)

See #347.

[jaredmorgs]

Coming in from the reveal.js discussion @mojavelinux and I were having the other day. I'm reading the content strategy with interest and definitely like the approach of Question-Answer approach @Mogztter described.

I've been working with an internal Google Search guy in Red Hat and he's been providing some interesting insights in how google is now structuring the Info Cards. If you don't know what this is, Google "install ruby on mac" and you'll get to see one.

Some trends are emerging about how Google discovers and indexes this content. It seems that if you add "How To..." into the title of a page, the lazy Googlebot is more inclined to crawl that page and if it is structured well, include it in an Info Card as a search result.

Stuff like giving concise/terse procedures in a structured form will help push your site up the rankings. I can see this being done easily by providing a procedure overview at the top of each "How To" page.

So instead of asking a question (I want to install Asciidoctor on Linux), give Google an answer (How to install Asciidoctor on Linux). Asciidoctor.org should already be a canonical source for all things AsciiDoc. I know it appears above methods.co.nz in most searches I've done. Why not leverage this by giving users Answer Cards and increase the traffic over to us.

[ggrossetie]

Another idea I had when writing benchmark document is to provide common template and explain how to use a particular syntax or extension.

• When writing a benchmark you should use the chart extension to display the results, tables to compare different setups, image macro to display screenshots, code block to reproduce the results, footnotes or bibliography to reference other benchmarks admonitions to draw attention on a particular result and so on...
• When writing scientific paper, you should use MathJax, use blockquote to quote an author...
• When writing technical documentation, you should include sources code, make a list of the known issues...
• When writing a book, you can add a dedication page, write a preface or an abstract...
• When writing a changelog...
• When writing a blog post...
• ...

Providing a common template is also extremely useful when you are not yet comfortable with a particular syntax because you have a working example to play with.

The reasoning behind is that I spent a lot of time on the "Syntax Quick Reference" when writing this benchmark document to find the best way to "present" the information.

[ggrossetie]

Proposal based on https://gist.github.com/graphitefriction/6adff94aa85087e7890c and the OpenShift's new documentation portal:

https://gist.github.com/Mogztter/254ac27ce2dc0b4a1f63

[danielkocot]

@jaredmorgs I like the idea with Answer Cards

[jaredmorgs]

We started discussing this in 2015. Let's make 2016 the year the Asciidoctor site gets refactored.

What are some further next actions we need to take to keep this marching forward?

[ggrossetie]

We started discussing this in 2015. Let's make 2016 the year the Asciidoctor site gets refactored.

Yes!

What are some further next actions we need to take to keep this marching forward?

I think we need to create a prototype (wireframe, simple web page) to see how we can organize the information: https://github.com/asciidoctor/asciidoctor.org/wiki/Docs-Information-Architecture

[danielkocot]

@Mogztter Are there any prototypes yet? Or do we start at a greenfield?

[rockyallen]

Some suggestions based on PR#518:

1. Add the menu bar to the FAQ and User Guide so they all look the same
2. Add breadcrumbs
3. In the FAQ, the questions are hard to see. Make the answers hidden unless asked for, similar to the Syntax Quick Reference. If this isn't possible, move the questions into the TOC.
4. Pull the "Conversion and Migration" articles out of the User Guide and link them from a new item "Migration" just before "FAQ" on the docs page.
5. Take the TOC off the docs home page - it should never get long enough to need it.

[mojavelinux]

I'm also thinking of making a project catalog page that would feature each project in the ecosystem. Each project could be represented by a card-like UI component for each project. It would have name, description, tags, maintainers, etc. That way, it's easy to see which projects there are and who is behind them.

[jaredmorgs]

I like this idea. Would make it really easy for someone wanting to contribute to a project that uses Asciidoctor.

[ggrossetie]

It's happening here: https://github.com/asciidoctor/asciidoctor/tree/v1.5.7-docs/docs (thanks to @graphitefriction)

Closing 🚪

[mojavelinux]

👍