Should the licence be stored centrally and appended to the top (or
bottom) of each page?
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 [email protected]: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
