Outline announcement post about new docs site

[mojavelinux]

The purpose of this issue is to outline the announcement post about the new docs site. The post should be concise, yet share all the vital information about the site, how it's constructed (at a high level), what we hope to achieve with it, and what's next for it.

Since the site is now live we'd like to turn this around quickly. The goal is to have a post up by Jan 12.

[mojavelinux]

One point the post should make is that the asciidoc component has been submitted as the initial contribution for the AsciiDoc Language project and will remain on this site at least until that project is publishing its own version, if not beyond that. This information can be found here: https://docs.asciidoctor.org/asciidoc/latest/#about-this-documentation

[mojavelinux]

Here's some high-level information about how the site is constructed: https://docs.asciidoctor.org/about/#documentation

[rahrah]

Hi,

Forgive me for chiming in here, but I'd like to say a big PLEASE to having the original Asciidoctor User Manual resurrected in single page form on your web site, or somewhere.

I use Asccidoctor most days for work (and play); it's a real pleasure to work with. But it's important for users with average ability like me to have an easily searchable (with the browser) resource for finding how to do something, or reminding oneself.

The Asciidoctor User Manual was a fantastic advertisement for a well structured document, a show case for the technology, and an invaluable reference resource.

Some of its best features:

• Available as a single page allowing for easy searches within the browser.

• The comprehensive contents in a sidebar (toc2) gives you an mental picture for how the material is presented, and a way of remembering the document structure.

• The entire scope of the document was laid bare before you. Random but optimistic clicking in the hope of finding that which you are looking for was not necessary.

• The manual was an easily downloadable reference resource for those without first world Internet connectivity.

Over the past few months I hadn't noticed that the availability of the old manual had diminished. But when a new project called for some more lookups and I found this:

https://stackoverflow.com/questions/62259617/asciidoctor-offline-user-manual-is-nowhere-to-be-found

The new web site as it stands, is, for me, nowhere near as helpful as the User Manual. There's no general overview, no easing in, no discussion of points, far fewer examples, and no showcase for the real beauty of the documents your wonderful work creates. It's like comparing a book with a man page. Please reconsider #989.

The manual was a rare thing, structured, informative and authoritative, and helpful; it was the very essence of that which asciidoctor was made to create. Please bring it back and continue to maintain it.

Thank you for reading, and forgive me for posting in a place that might not be appropriate.

Thanks,

===Rich

[mojavelinux]

We will not be restoring the old user manual as it is now substantially out of date. However, we can consider adding a single page mode. Please file that issue at https://github.com/asciidoctor/docs.asciidoctor.org/issues

The outcry about it not being as useful is misguided. The content on the new site is based on the content from the old site. The only difference is that the content has been a) organized into multiple pages and b) updated and revised for accuracy. In fact, it has many more gentle introductions than were there before (for example: https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/ and https://docs.asciidoctor.org/asciidoctor/latest/). So the statement that there is "no general overview, no easing in, no discussion of points, far fewer examples, and no showcase" is completely invalid.

It may not be your intention, but you have insulted the extremely hard work we have put in to making a new and improved documentation site which has taken at least a year if not more. So I find your comment to be whole inappropriate and not at all helpful. I also don't appreciate you hijacking this issue, which has absolutely nothing to do with your rant.

[mojavelinux]

I also want to add that the new search gets you were you need to go substantially faster than relying non a browser-based search. A browser-based search only searches from top to bottom for an exact match. This search will find relevant results anywhere in the docs and even has support for exact matches (if enclosed in quotes). So your point that the search was better before is plain wrong.

[rahrah]

It was truly not my intention to offend anybody, nor to disrespect any of your work. I am extremely grateful for all the hard effort you have put into the project and only wish it and all of you well.

I am very sorry for causing any offence, hurt or pain. I merely wished to make a request and point out the personal issues I felt about the documentation. Forgive me for any pain or feelings of insult I may have caused. Your work and your project is something about which I very much care.

Once again, I'm very sorry: I did not intend to insult, rant, troll or hurt, and I am extremely sorry for any pain my request created.

Best wishes,

===Rich

[mojavelinux]

Thanks Rich. I appreciate the follow-up. I'll put it behind us.

Having said that, I do consider your request to have a single page version both reasonable and valid. There is a related issue open to generate a PDF for download, but I think we still need a separate issue for single page HTML. See asciidoctor/docs.asciidoctor.org#55

[rahrah]

I created an issue as per above.

asciidoctor/docs.asciidoctor.org#56

Once again, I'm very sorry giving offence.

Best wishes,

===Rich

[mojavelinux]

Thanks Rich. I appreciate you taking the time to create that issue. We'll continue the conversation about the single page HTML in that issue.