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
132 stars 40 forks source link

Simplified in a project page context vs full documentation. #106

Open apj68 opened 3 years ago

apj68 commented 3 years ago
abelsromero commented 3 years ago

For other repos we remove most content tand left the minimal to point to the official docs. That way we don't need to maintein duplicated content twice. Also users get used to go to the docs site, and get the same experience for all projects (at least, those published).

PS: I think we should also review the https://github.com/asciidoctor/asciidoctorj README if the goal is to reduce READMES

apj68 commented 3 years ago

@abelsromero , do you think the pull request needs more to come out of the README? I tried to trim it back to keep it simple but leave enough to give an idea of how it was used. I see that the other examples you provided are a bit more spartan, I can take more out if needed.

abelsromero commented 3 years ago

do you think the pull request needs more to come out of the README?

It's more of an open questions to discuss, but I think we could trim more, for example I'd remove the "Resources and help". Regardless, keep in mind I am not the repo ower, just trying to offer a transversal view aligned with other projects in the family.

apj68 commented 3 years ago

Let me take another crack, I agree the resources can go into the main documentation. The two examples you provided are definitely brief.

apj68 commented 3 years ago

Ok, I removed the help section. I feel like the Quick Start is not useful without the samples so I left them in.

Also, I'm new at this and tried to squash the commits but I seemed to be going in a circle. I'd squash then I'd have a conflict, resolve the conflict, new commit, squash, new commit... etc!

abelsromero commented 3 years ago

The only thing I'd would do is adding a link to the docs to the top.

Also, I'm new at this and tried to squash the commits but I seemed to be going in a circle. I'd squash then I'd have a conflict, resolve the conflict, new commit, squash, new commit... etc!

If you want to add changes to the last commit without creating a new commit, use git add WHAT_IS_NEEDED, then git commit --amend --no-edit. You will still need to force-push but avoid the hasle of squashing over and over.

@johncarl81 wdyt about this?