Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
RFE: Convert README.adoc into a Fully Fledged Asciidoc Guide #153
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.
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?
To combat this, I would use the Asciidoc
referenced this issue
Mar 24, 2015
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.
HubPress is specifically designed for blogging. It groups small documents
Theoretically, HubPress could be turned into a documentation hub. There
I'm sure this list is not exhaustive.
The JAQ allows you to spin up a user guide the size of the HubPress README
This is the only limitation, and something that could be fixed by the right
On Mon, May 4, 2015, 11:51 MetaSean firstname.lastname@example.org wrote:
@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
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.