Project: Infinispan (App Definition and Development / Database)
File: TODO.md

28-30.07.2016 Read documentation aloud to ensure the sentences flow Dont take background concepts for granted, but also dont repeat information. Link to existing explanations. Order is important: if a concept builds on other concepts it should come after them. Forward linking should be a last resort A picture / code-snippet / example are worth a thousand words (but always provide further explanation about meanings) If you include a code-snippet ensure it is valid code (i.e. it should compile) and that it works against the version being documented. Chapter titles should be as succinct as possible Be consistent with terminology / hyphenation / character case Never include Infinispan in the chapter title unless absolutely necessary The correct spelling of Hot Rod is as two separate words. Remove documentation which doesnt apply anymore. Ensure that links work, i.e. the targets exist Ensure that links between documents are relative to the current version. Absolute links to specific versions and to the dev and stable placeholders MUST not exist Ensure that links that need to be versioned use the {infinispanversion} asciidoc macro Replace the sid-XXXX anchors with meaningful ones Ensure that references to the current Infinispan version use the correct placeholder Maybe add annotator.js support so users can comment directly on the document like a PR review Prefer SVG when possible as it is very compact and provides the best scalability Alternatively use PNGs with indexed colors (dont use full RGB images), with reasonable sizes and cleaned up with pngcrush Avoid gradients / backgrounds in bitmap formats Always add a caption This document is woefully full of TODOs. If we cannot DO them, they should be removed It should refer to existing tutorials where possible instead of duplicating information It should contain some of the information from the containerized tutorials Prefer REPL examples using jjs as it comes out-of-the-box in Java 8 Always provide both a programmatic and declarative example for each configuration. Provide use-case-driven examples ? Remove the false claim of supporting the JCache API in our Cache interface Link alternative APIs (JCache, Spring, Functional) We should move the Cluster Executor documentation to the chapter about Distributed Execution and document why we have both (Will) The general organization of the document is very uneven in discussing configuration features (eviction, persistence) and API features at the same

These chapters should be reorganized so that configuration features are grouped separately from APIs. With the ongoing work to remove the dependency on JBoss Marshalling for internals, and aiming to have a fully pluggable user marshaller, this will need to be rewritten in the context of Galders PRs Possibly show how one would write an externalizer which supports backwards/forwards compatibility Need to redo images. Add missing parts (CQ) Refactor the WIKI page into the documentation, possibly as its own chapter. This feature no longer exists, it needs to go. Move under an overarching Integrations chapter Move to its own paragraph under Integrations Do not mention EHCache its not relevant Mention proper artifacts (spring5) The chapter is currently called Server modules but this is confusing as we are really discussing the remoting protocols and neither the WildFly modules nor Infinispan Server This should be turned upside down, looking at the protocol side first, and then detailing the server-side implementation aspects. Remove the RHQ section and other mentions of it Move the CLI chapter under here Since we are describing an advanced API this needs to be moved further up Document the new async design and provide some useful examples Actually refactor this chapter into a more general chapter about running in different cloud/container environments AWS Docker OpenShift / Kubernetes Google Compute Engine Azure ... Remove this chapter and find a way to generate the information into the configuration reference Move under an overarching Integrations chapter Remove the open tasks Mention Spring Session Eventually will also contain Pauls Tomcat adapter Move under an overarching Integrations chapter Remote JCache configuration, example of properties (at least IP:port) Place under Integrations The console should get a dedicated chapter outlining the different parts (Clusters, Nodes, Caches, Configuration) Dont go overboard with screenshots Reference the video Ensure that all public APIs have JavaDoc Ensure that all parameters are documented with the @param doclet Can this be somewhat automated via checkstyle ? We get many recurring questions on the forum / stackoverflow / IRC / etc. Try to distill some of the most significant ones you have answered successfully. Even questions that are related to product (sme-jdg, customer portal, etc) can be of use (obviously purged from any product reference) Things we CANNOT do are also important, and we should point out any limitations