Closed msgilligan closed 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.
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.
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.