Comments (4)
+1 from my side to keep documentation examples under build and test cycles.
Not sure if we should first take a step back maybe and review what we want to accomplish.
Here's my gist after updating the docs for the Java API query dsl examples:
What we have at the moment is the following:
https://www.elastic.co/guide/en/elasticsearch/client/java-api/current/bool.html
IMHO on the one hand this is not enough as for most queries it doesn't cover all options, so no real reference documentation there. It duplicates documentation as well as what is written there to some part is written in JavaDoc already. On top it's never built so easily forgotten when ppl change the API.
Another approach I've seen in the wild:
To me those are complimentary to the reference style docs JavaDoc typically provides: It's giving real world examples centred around some topics. On top it has the advantage of being under build and test cycles.
Lastly there's the Lucene JavaDoc only approach:
https://lucene.apache.org/core/4_1_0/core/index.html?overview-summary.html
Close to the code, examples still not under build and test cycles.
Me personally if I was a user I would love to see the second type of docs - could be as real code examples in some test package. If it's done using the style @dadoonet outlined above it would be better in line with the rest of our documentation - great as well. For such documentation I personally find it frustrating if there are errors in the docs, so to me it would be really important to keep them under build and test cycles.
In addition I would wish for detailed reference docs in our JavaDocs, potentially linked from the examples above.
from docs.
It basically means that when a developer changes whatever part of code, the documentation is automatically updated with the new content.
+1 and will help our doc from becoming stale over time :)
from docs.
Hmmm. Just found this doc today: http://mrhaki.blogspot.fr/2014/04/awesome-asciidoc-include-partial-parts.html
May be this is something we can use easily? I'm going to give it a try.
from docs.
Closed by elastic/elasticsearch#24354. Thanks to @nik9000 !
from docs.
Related Issues (20)
- Right hand side on Logstash plugins guide is too short HOT 4
- Add new landing page CSS to this repo HOT 2
- Add missing OpenGraph (og:) meta tags
- Adding the Android APM agent to the build
- Revisit information architecture for docs landing page and latest
- Fix air-gapped docs navigation HOT 1
- Remove Azure Marketplace and Resource Manager docs
- There is a link broken to the azure marketplace. Go here--> https://www.elastic.co/guide/index.html and scroll down to “Subscribe” and click on ‘Azure Marketplace’ (404 error) #1388 HOT 7
- Footnotes start with number 2 HOT 2
- linked worktrees unsupported when running `build_docs`
- [BUG] Notes section icon prevents characters from being selected
- Differences in the breaking change page for Kubernetes Autodiscover of all Beats
- The `Copy as curl` function doesn’t work for PATCH requests HOT 2
- Feedback from testing operator hub integration releasing ECK 2.12.0
- ESQL Docs: Copy as cURL and open in console for ESQL HOT 1
- race in docs build causes build failure unrelated to changes
- Missing a parenthesis at ECS node.js logging
- Error [ERR_REQUIRE_ESM]: require() of ES Module "xxxx" is not suppored
- Compile error for golang ECS logging
- Add navigation banner to "classic" docs HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docs.