Documentation Improvements

[AlexDBlack]

Recently I read through the Konduit Serving documentation available on gitbook (and synced to this repo): https://serving.oss.konduit.ai/ Overall, what has been done so far is pretty good. However, there's some things I think we can improve, most of them easy fixes. We can split some of these items out into their own github issues for tracking if necessary.

Also I could be wrong on some of this (still learning codebase and current status).

General thoughts/comments:

• https://github.com/KonduitAI/konduit-serving - readme.md and repo description - doesn't link to docs at serving.oss.konduit.ai
• konduit.ai - doesn't link to serving.oss.konduit.ai (not sure if intentional, give we haven't officially launched/released yet?)
• No mention of the "data type conversion between pipeline steps" that (I believe) Konduit serving supports Edit: looks like this is for the output only (not between intermediate pipeline steps). Although, there are some implicit conversions between dl4j related and python steps. (For example, ND4J -> numpy and vice versa).
• No mention of PMML conversion endpoints mentioned in docs (not sure if CLI supports this too?)
• GitBook styling - I'm personally not a fan of the dark blue code blocks... IMO the strong contrast draws too much attention to the code relative to the text. Maybe light gray instead?

Later/future:

• Should we have a technical explanation page?
• Add debugging page - self-help for common issues?
• PMML examples
• "Konduit Zoo" / "Konduit Hub" - easy setup/recipes for standard pretrained models?
• Finish all empty/placeholder pages

---

---

Page: https://serving.oss.konduit.ai/

• IMO we need a diagram (flow chart) here showing pipeline steps, with logos - TF, ONNX, PMML, DL4J, Python, Java etc. Maybe Numpy, Arrow, CUDA etc.
  • First page is only text ATM; explaining it visually too should help users to more quickly understand what it and why they should care
• Clarify what PMML means in practice - i.e., "can be used to serve models from libraries X, Y and Z (using built-in conversion)"
• Maybe mention also Java as an option for pipeline steps (1 line after datavec but before usage probably)

Page: https://serving.oss.konduit.ai/quickstart/quickstart-python

• Is it possible to define the configuration programmatically, instead of via a YAML file? If so, we should show this first/too
• A list of API methods on the server and client would be nice. I see server.start(), client.predict() - let's get the full list in a table perhaps?

Page: https://serving.oss.konduit.ai/installation

• Mentions CUDA 10.1. But TF <2.1.0 is CUDA 10.0, so not correct? (>=2.1.0 is 10.1)
• Clarify that PMML doesn't support CUDA
• Do I need to have CUDA installed? CUDNN?
• "Ensure that you have JDK 8.0 installed"
  • This should probably be 8.0 or higher
  • Do we need a link on how get Java? (I'm just thinking for Python devs who have never touched Java before)

Page: https://serving.oss.konduit.ai/building-from-source

• Clarify at the very top: When does / doesn't the user need this? If they don't need it, what's the easier alternative?
• There's lots of different modules here... as a user/developer, how do I decide which ones I need? Table, diagram, and/or flow chart etc?
• "Python bundling is not encouraged on ARM platforms" - that's vague. Why? Is it unstable? Broken? Limited?
• "> konduit init --os " - is cross-compilation possible? - i.e., say I want to build on mac but deyloy on Linux+CUDA (clarify either way)
• "Known issues - konduit init fails for linux-86_64-gpu (#115)" - issue is already closed.

Page: https://serving.oss.konduit.ai/yaml-configurations

• Clarify what "NDARRAY" type actually means. Is this NumPy format?

Page: https://serving.oss.konduit.ai/model-monitoring/monitoring-grafana

• "...to assist with troubleshooting" -> mention monitoring and debugging; it's not just (or even primarily) about problems
• Maybe a better example image of the pipeline charts would be good, so it's a bit more appealing to users?

Page: https://serving.oss.konduit.ai/examples/python/tensorflow-model-serving/tf-bert

• "This notebook illustrates..." -> it's a page, not a notebook

[ShamsUlAzeem]

@AlexDBlack thanks for a thorough review. I'll create an epic out of it and create a list of issues for the fixes.

[ShamsUlAzeem]

Following are the related issue links or list of things to do based on the above discussion:

• [ ] https://github.com/KonduitAI/konduit-serving-docs/issues/8
• [ ] https://github.com/KonduitAI/konduit-serving-docs/issues/9
• [ ] https://github.com/KonduitAI/konduit-serving-docs/issues/10
• [ ] https://github.com/KonduitAI/konduit-serving-docs/issues/11
• [ ] https://github.com/KonduitAI/konduit-serving-docs/issues/12
• [ ] Need to discuss the technical explanation page. Things like what it should be in general and what it should cover
• [ ] https://github.com/KonduitAI/konduit-serving-docs/issues/13
• [ ] https://github.com/KonduitAI/konduit-serving-docs/issues/14
• [ ] https://github.com/KonduitAI/konduit-serving-docs/issues/15
• [ ] https://github.com/KonduitAI/konduit-serving-docs/issues/16
• [ ] https://github.com/KonduitAI/konduit-serving-docs/issues/17

[ShamsUlAzeem]

@AlexDBlack what should the technical explanation page contain in general?

[AlexDBlack]

Another thing: https://serving.konduit.ai/installation#set-environment-variables-manually

This talks about setting an environment variable to point to a JAR file - but then has zero information on where the JAR comes from.

@AlexDBlack what should the technical explanation page contain in general?

Sorry, didn't see this until now. Basically architecture, how it works internally.