WIP Reorganize docs page

[ggrossetie]

This is a work in progress to reorganize the docs page.

I stick with the default stylesheet but I think we will need to add a custom style to display "Info Cards" / "Answer Cards".

We will also need a search feature or at least a system with tags to ease the navigation.
For example if I want to convert my documentation to HTML5 with diagrams in a Maven build, I can select html5, diagram, maven and java tags and the system will show the relevant tools and their documentation.

Fixes #366

[ggrossetie]

I think there's too much content in this page. Maybe we should split this page "Getting started" and "Ecosystem" ?

[mojavelinux]

Maybe it's time to start using rawgit links to import the READMEs. We gotta start somewhere:

include::https://cdn.rawgit.com/asciidoctor/docker-asciidoctor/master/README.adoc[]

WDYT? We could also link to a specific tag.

[mojavelinux]

This is definition an inspired start. I already feel less stressed when viewing these pages.

A few things to refine at this stage:

• The links to the Docker install guides should be in the same list as Linux, OSX and Windows rather than as a subsection. Use the Docker logo to make it parallel. (This entry will just have two links instead of one).
• Can we use SVGs for the logos for Linux, OSX, Windows and Docker?
• We may want to get rid of the "Asciidoctor Project" sidebar for any page that isn't an index / entry page. It's just taking up space.
• Let's add the Docker pages in a separate pull request and use include instead of copy-paste.

[mojavelinux]

Oh, and I think "What's new" should point to the blog (or a tag on the blog).

http://asciidoctor.org/news/tag/release/

Granted, we need to get better at doing blog posts, but that's why I've opened #520.

[ggrossetie]

Maybe it's time to start using rawgit links to import the READMEs. We gotta start somewhere

Good idea. Do we need to add page-layout attribute on each projects README ?

This is definition an inspired start. I already feel less stressed when viewing these pages.

Thanks, this is far from finished but hopefully this will push things forward.

The links to the Docker install guides should be in the same list as Linux, OSX and Windows rather than as a subsection. Use the Docker logo to make it parallel. (This entry will just have two links instead of one).

OK.

Can we use SVGs for the logos for Linux, OSX, Windows and Docker?

Sure, I just didn't find good resources for logos in SVG format.

We may want to get rid of the "Asciidoctor Project" sidebar for any page that isn't an index / entry page. It's just taking up space.

True, maybe we could replace sidebar with TOC on the left ?

Let's add the Docker pages in a separate pull request and use include instead of copy-paste.

OK.

Oh, and I think "What's new" should point to the blog (or a tag on the blog). Granted, we need to get better at doing blog posts, but that's why I've opened #520.

I was thinking to write an overview of the latest release and a few words on the newest projects. But we could also write a blog entry and point to the blog (avoid redundancy).

[ggrossetie]

Use the Docker logo to make it parallel. (This entry will just have two links instead of one).

I think the AsciidoctorJ docker container is too specific for the "Install Toolchain" section. It's more about integrating AsciidoctorJ in an application server and running tests than installing Asciidoctor toolchain. Wdyt ?

[ggrossetie]

True, maybe we could replace sidebar with TOC on the left ?

I think we need to resolve this issue awestruct#228 to be able to put the TOC on the left ?

Here is a preview of what this could look like:

Just saw that the TOC is on the right on the Asciidoctor User Manual. I'm fine with that but is there any reasoning behind this choice ?

[mojavelinux]

Do we need to add page-layout attribute on each projects README ?

That won't be necessary. We can inject an attribute entry for it above the include directive (since we can add new document attributes above the document title).

:page-layout: awestruct
include::...[]

I just didn't find good resources for logos in SVG format.

Perhaps http://svgporn.com/ (if you're willing to disregard the crudeness of the site name).

maybe we could replace sidebar with TOC on the left ?

I definitely like that idea! We might even be able to make it possible to toggle it, like on https://docs.mulesoft.com/.

I don't want to spend too much time fixing the styling since we need to redesign the whole site anyway. So we'll focus more on the mechanics (just making it appear).

I think we can monkeypatch Awestruct in the _ext/pipeline.rb file to make the Document object available for creating the TOC. But an upstream fix would be ideal.

I was thinking to write an overview of the latest release and a few words on the newest projects.

I'm hoping the blog can serve that purpose. However, I'd also be open to a new releases page if we automate it. We can pull information from the releases pages on GitHub.

I think the AsciidoctorJ docker container is too specific for the "Install Toolchain" section.

I agree. We should focus on just the general docker container that provides the basic toolchain. We can document the AsciidoctorJ docker container elsewhere.

is there any reasoning behind this choice (to put the TOC on the right) ?

We were experimenting. We should probably switch it back because I'm not convinced that I even like it on the right.

[ggrossetie]

That won't be necessary. We can inject an attribute entry for it above the include directive (since we can add new document attributes above the document title).

Include remote files are not working out of the box. Do we have a preprocessor ?

include::https://cdn.rawgit.com/asciidoctor/docker-asciidoctor/master/README.adoc[]

Perhaps http://svgporn.com/ (if you're willing to disregard the crudeness of the site name).

I finally found logos in SVG format.
I still need to find SVG logos for langages (Groovy, Java, JavaScript, Ruby) on the developer guide.

I definitely like that idea! We might even be able to make it possible to toggle it, like on https://docs.mulesoft.com/.

Wow that's nice 😄

I don't want to spend too much time fixing the styling since we need to redesign the whole site anyway. So we'll focus more on the mechanics (just making it appear).

Ok I've added missing links.
All contents should now have at least one link.

I think we can monkeypatch Awestruct in the _ext/pipeline.rb file to make the Document object available for creating the TOC. But an upstream fix would be ideal.

Do I need to wait for the 0.5.7 upgrade #526 ?

I agree. We should focus on just the general docker container that provides the basic toolchain. We can document the AsciidoctorJ docker container elsewhere.

Done, this documentation is now on the developer Guide.

[ghost]

Would it be possible to chunk the user guide?
Currently I find navigation to be slow (on first load, because of both the large dom & the initial download) and messy (= difficult to read).
As this is software to produce html, I think it’s important that the website is appealing. For example Middleman and Awestruct make a much better first impression than Jekyll or Nikola, and I think this is a major selling point (even if you know that you could customize your output as much as you want)

[ggrossetie]

Would it be possible to chunk the user guide?
Currently I find navigation to be slow (on first load, because of both the large dom & the initial download) and messy (= difficult to read).

It's true that the navigation is slow but I'm often using ctrl+f on my browser to find a relevant information. If we split the user guide on several pages it will be harder to find all occurrences of a term.

Maybe we could let the user choose between a single HTML page and one page per section (level 1) ?

[ghost]

This is a good point (ctrl-f).
Letting the user choose would be cool, but maybe painful to maintain?
Maybe a good compromise between searchability and readability could be implementing a foldable toc: navigation would be faster and better, because we would just get an overview of the contents, but we would still be able to make full text searches

[mojavelinux]

Would it be possible to chunk the user guide?

Yes, we just haven't done it yet. The focus has been on filling in the missing parts of the manual.

Likely we'll break at the part or chapter level, where there are very clear distinctions and least likeliness of breaking the scope of Ctrl+F. Of course, we'll still provide an all-in-one option. Regardless, this should be tracked as a separate issue.

[mojavelinux]

I'm often using ctrl+f on my browser to find a relevant information.

I do as well, but right now the scope is so large that it actually makes Ctrl+F less useful. If the content were more focused, Ctrl+F could be a more useful navigation device. That's the key about chunking...it has to be done with semantics in mind.

[mojavelinux]

As this is software to produce html, I think it’s important that the website is appealing.

That's the direction we're heading right now.

[mojavelinux]

Maybe we could let the user choose between a single HTML page and one page per section (level 1) ?

We have to do this very carefully. I think the best way is to provide a link in the partitioned version to the all-in-one / "printable" version. Power users will bookmark that. What we want to avoid is this mess:

User Manual :: [Single page HTML] [Multipage HTML] [PDF]

^ That is a UX nightmare.

We want a single entry point with options from there to get a different view....or even find a way to make it so seamless that the reader never has to give it much thought.

[mojavelinux]

Include remote files are not working out of the box.

They are now. Just sync with master. I enabled it when I upgraded to 0.5.7. If that still doesn't work, just let me know.

[ggrossetie]

They are now. Just sync with master. I enabled it when I upgraded to 0.5.7. If that still doesn't work, just let me know.

Rebased on master and this is working great! Well done 👍

[ggrossetie]

To illustrate technologies we could use Devicons: http://vorillaz.github.io/devicons/#/dafont

[mojavelinux]

I like this page as a way to show a catalog of projects in the ecosystem.

https://github.com/piotrmurach/tty-progressbar