The wiki-outline.py script exposes gaps and inconsistencies in how pages are structured.
Standard structure
A potential standard structure:
Why and General; motivation (not JVM-specific, but about the value)
Sample build script code in the writing? Or better to refer to the code repo with line numbers? (Line numbers are helpful but annoying to maintain)
Specific to JVM (JVM, Gradle and Maven)
Spots to insert advice for other build tools & language ecosystems -- TO DISCUSS
Tips
Going further
Acceptance criteria
Pages make sense in their structure following shared patterns. This depends on where a page is in the top-level structure, and what makes sense for that page. For example "Preface" looks quite different from other pages, but all the "Topic" pages should have similar structures.
TODO markers for filling in sections we want but which do not yet have writing, and easy to find these for filling in writing gaps for standard sections (ie, `grep '**TODO**').
Out of scope
The "shift security left" page has a block of TODO at the page top. This needs restructuring to incorporate sensibly in the rest of the page, but is out of scope of this card.
Tasks
These depend on agreement on standard structure.
[x] 1. Authors discuss what a typical page structure should be.
[x] 2. Motivation section at page tops without a special header (ie, the first text a reader encounters for a page) -- OK if a placeholder for later writing -- each needs to explain the value of implementing a topic. This is not a ## section but the starting text for the page.
[x] 3. Specific writing for implementing with Gradle -- OK if a placeholder for later writing
[x] 4. Specific writing for implementing with Maven -- OK if a placeholder for later writing
[x] 5. Add "Tips" section to suitable pages -- OK if a placeholder for later writing
[x] 6. Add "Going further" section to suitable pages -- OK if a placeholder for later writing
[x] 7. Placeholder sections have a bold "TODO" marker to indicate that it needs writing
More than Gradle/Maven
Prepare for the sections being expandable for other build tools/platforms/languages. TO DISCUSS
Separate each section into General advice, and advice Specific to JVM.
Add a Discussion section to break up advice from why and discussion.
Context
The
wiki-outline.py
script exposes gaps and inconsistencies in how pages are structured.Standard structure
A potential standard structure:
Acceptance criteria
Out of scope
Tasks
These depend on agreement on standard structure.
##
section but the starting text for the page.More than Gradle/Maven
Prepare for the sections being expandable for other build tools/platforms/languages. TO DISCUSS
Separate each section into General advice, and advice Specific to JVM. Add a Discussion section to break up advice from why and discussion.