RFE: Convert README.adoc into a Fully Fledged Asciidoc Guide

[jaredmorgs]

I think the way the README.adoc is growing now, it actually deserves to become it's own User Guide. I have been using the https://github.com/asciidoctor/jekyll-asciidoc-quickstart to produce a static docs site, and it works really well. See the results at http://jaredmorgs.github.io/Pinball_Arcade_Users_Guide_Android/

Rather than just "doing it", I wanted to create this issue so that the community translators can ask any questions they might have about splitting their work out into separate contained User Guides. I would also need some assistance with some aspects of the JAQ site to make it compatible with multiple doc versions and languages.

Site Challenges
The JAQ is great for one document, but I'm not sure how to extend it for the same doc in different languages, or multiple guides in different languages (thinking forward to the API guide @anthonny ).

At the moment, the Travis CI job that runs automaticially when commits are made will build any number of books on the site, but the main index page needs to be manually updated when new language versions are added or new guides are pushed into the docs site.

What would be great is to have some way of automatically updating the index.html landing page as the front-end of the docs portal. Some sort of extension to the Travis CI job or some pre-configured GEM that handles the front page regeneration. Any ideas?

Translation Considerations
I had considered implications about translation using this approach. I don't want to discourage community translators from contributing becasue they may feel the docs are not "easy" to update.

To combat this, I would use the Asciidoc include code to break up the chapters into smaller chunks so users don't have to manage the whole file. It works quite well, and is how I set up the Android Users Guide linked above.

README modifications
The README becomes the Getting Started instructions (so how to fork and initially run) only. The user guide will also contain this basic set of instructions. The rest of the README content is migrated into the User Guide.

[metasean]

I feel like I'm misunderstanding something important, but why don't you just write the User Guide in HubPress?

Personally, one of my hopes for HubPress is that I can have a blog section, but I can also have more static pages (e.g. #36), and that I can us it for project documentation.

[jaredmorgs]

Great question!

HubPress is specifically designed for blogging. It groups small documents
(blog posts) into discreet nodes, with tags and other blog-specific
metadata.

Theoretically, HubPress could be turned into a documentation hub. There
would be some work required though:

• a suitable documentation style (for example, the Asciidoctor Foundation
  style) mashed into the Ghost Theme style constraints.
• part of that style would require a launch page with a side navigation for
  accessing Product > Book > Language
• back-end changes to support include statements
• support for accessing and editing Asciidoc files in a file tree structure.

I'm sure this list is not exhaustive.

The JAQ allows you to spin up a user guide the size of the HubPress README
in about 30 minutes. You do need to use a PC to set it up (using the Ruby
Gem system). Once that is done and you have configured the Travis job,
building the guide and pushing it up to docs.hubpress.io is seamless. But
it is only good for one book per JAQ repo.

This is the only limitation, and something that could be fixed by the right
people with experience in this area.

On Mon, May 4, 2015, 11:51 MetaSean notifications@github.com wrote:

I feel like I'm misunderstanding something important, but why don't you
just write the User Guide in HubPress?

Personally, one of my hopes for HubPress is that I can have a blog
section, but I can also have more static pages (e.g. #36
#36), and that I can us
it for project documentation.

—
Reply to this email directly or view it on GitHub
#153 (comment)
.

[mojavelinux]

@jaredmorgs It's interesting that you bring this up because we're having the exact same thought about the READMEs in the Asciidoctor project. In each project, the README is trying to be the User Guide, which makes it a poor README. On the other hand, we have a separate User Guide hosted in the website repository that tries to cover things that are covered in each project.

Regardless of where the files are hosted & published, it's clear that a README and a User Guide are not the same. What's great about AsciiDoc is that you don't have to settle on a final solution right away (whether it's JAQ or HubPress pages). The content is portable and can be easily migrated from one publishing pipeline to another.

I do think it's worth experimenting with using JAQ to handle the User Guide. I think you're right that it will unlock the power in the publishing toolchain that is required for proper technical documentation.

The one downside of using a separate repository is that the documentation no longer moves with the code. However, this can be alleviated by having branches in the documentation repository that mirror the branches in the code repository. You'd view them as a single logical repository even though they are separate. Until we think of a way to layer JAQ over an existing code repository, that may be the approach you need to take. (Another idea is to have JAQ retrieve documentation files from a separate repository, so it acts as a shell but the content is pulled in from an external source).

I'm not sure why multiple documents in JAQ presents a problem. Jekyll should have no problem building any AsciiDoc files it finds. Generating the index page dynamically should be possible by using a Jekyll plugin. The sitemap plugin https://github.com/jekyll/jekyll-sitemap does something similar. It looks at all the files in the repository and puts together a summary page. This use case seems no different. You can start with putting it in the _plugins directory and maybe eventually graduate it to a gem.

I'm also excited to see use getting into translations. I think HubPress will be a great playground for understanding how to organize and manage them with this toolchain. Separating the content into discreet chunks makes it easier for a translator to digest and to track changes in the master. We can also develop tools around it.

[jaredmorgs]

This is an old issue now, and has since been resolved by migrating the guides to GitBook.