search

asciidoctor / asciidoclet

:clipboard: A Javadoc Doclet based on Asciidoctor that lets you write Javadoc in the AsciiDoc syntax.
https://github.com/asciidoctor/asciidoclet
Apache License 2.0
133 stars 40 forks source link

Make documentation easier to find and better-structured. #47

Closed msgilligan closed 8 years ago

msgilligan commented 8 years ago

I've used AsciiDoctor for a while, but am currently using Asciidoclet for the first time. It hasn't been clear where the best place to go for information is.

Currently, it seems the (two?) major sources of "user guide" or "getting started" information are:

Problems with the README:

My suggestion is to create a "User's Guide" in a doc folder in this repository. We can move some content from the README and (more important) the 1.5.0 release announcement into the User's Guide and then add build instructions, links to the JavaDoc, etc. to the README. The question, then, is where to put the rendered user's guide.

p.s. I'm willing to help with this work.

msgilligan commented 8 years ago

PR #49 provides links to JavaDoc and to the Release 1.5.0 announcement/notes which partially addresses this issue.

The next step, I think, would be to create a User's Guide in /doc, moving some content out of the README and combining it with content from the Release 1.5.0 announcement/notes.

johncarl81 commented 8 years ago

Honestly I like having the README be the user's guide. I've found that most people use the github project page as a quick-start and reference. I think that burying the user's guide into a folder may hurt adoption in that regard.

That being said, if you feel that we need a more expansive user's guide, feel free to open a PR.