Hi David, I would be happy to do this task. But how to avoid conflicting PRs? Matthew
On 03/12/2018 04:21, David Blevins wrote:
Hello hopeful contributors! As of this weekend we have two new index pages for our documentation on the website: - http://tomee.apache.org/tomee-8.0/docs/ - http://tomee.apache.org/tomee-8.0/examples/ The source for each of these index pages is generated by walking over each Markdown or Asciidoc file in these two sections of the main repo and looking for an `index-group=Foo` header in the document. That's how they get grouped. - https://github.com/apache/tomee/tree/master/docs - https://github.com/apache/tomee/tree/master/examples In the 'docs' directory alone there are 165 files that have "Unrevised" as the header or no header at all. We need to get a header on all 165 of them. If you're looking for a way to contribute, there are 165 of them right there. At 15 minutes each document that's 2475 minutes or 41.25 hours of community work. ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ :) What we need is each doc to be reviewed, checked for any formatting issues such as inconsistent h1, h2, h3 usage, then make your best guess on what the topic is (JavaMail, JMS, CDI, JPA, etc), then set that as the header `index-group=JMS` and submit a PR along with any updates to the document you think are good (maybe none at all) Here's a couple sample commits: - https://github.com/apache/tomee/commit/bdee81d34c60644b755621254a535d0d8757eb21 - https://github.com/apache/tomee/commit/e2190a47c211c870680d761efd6d025d935546c7 If you'd like to build the docs locally, run this long command and then open your browser to http://localhost:8080 - git clone g...@github.com:apache/tomee-site-generator.git && cd tomee-site-generator && mvn clean compile -Djbake.http=true On the formatting inconsistencies: - We use to use Confluence. There are actually some pages still with that old format. - Some docs randomly start at h3 or h5. They need to start at h1 and strictly not jump to h3 without an h2 in the middle. - If you have the energy to convert it from Markdown to Asciidoc, yay! We need to do this for both the docs and examples. - https://github.com/apache/tomee/tree/master/docs - https://github.com/apache/tomee/tree/master/examples
