Over the years we’ve created a number of GitHub repos with tools and associated content that can help us in the Observability space, such as log generation and replay, to help validation Fluentd and Fluent Bit configurations (or an OTel collector of choice). This extends to the most recent efforts with imp,eating the OpAMP capabilities and configuration UI.
Tools are good, but documentation that is easy to work with is a key to helping users be successful. To support that we have established a consolidated set of pages using GitBook which can be found at:
The nice thing about GitBook, is that it brings together the various resources such as markdown , HTML etc and creates a friendlier experience. It also keeps in sync with the GitHub repos.
New logos
As we’ve established the GitBook content, and using AI makes us less artistically able people to create graphics and logos, we’ve created a couple of logos for the older repos as well:
Fluent Bit Classic configuration to YAML conversion tool.
Log Generator can create synthic logs, or replay application logs to simulator a real system logging.
Before joining Oracle I used to typically refer to a couple of key resources from Oracle – docs.oracle.com, and occasionally developer.oracle.com and ateam-oracle.com. We’d obviously use cloud.oracle.com and the main oracle.com to be able to reference published stats, success references etc. Now I’m part of the company and working in the OCI product team with an outbound side of things, I needed to gem up on all the assets that exist. So that we can help contribute, and ensure that they are up to date etc. In doing so, the number of resources available is so much more than I’d realized.
Upon reflection, this may have been from the fact we didn’t drill down deeply enough, also in part that Capgemini has its own approaches and strategies as well.
This in part is linked to the organizational structures e.g. OCI Product Management’s outbound work overlaps with the Marketing Developer Relations, for example, something that is inevitable in an organization that provides such a diverse portfolio of products.
For my own benefit, and for others to exploit, the following table summarises the different areas of information. The nature of the content and – where content overlaps or is presented in different ways.
We’ve moved this content so it can be easily revised to here (and accessible from the site menu). But also available here …
The members of this team are the ‘gurus’ of product applications. These cover a range of domains – structured in a similar way to blogs.oracle.com with different posts. These posts represent patterns and solutions to problems encountered by the team. How to, or not to implement things. This can overlap with some blogs in so far as both product blogs and A-Team blogs may address how to leverage product features.
Developer relations lead, which covers not only Oracle products but also the application of open source. By its very name, there is a strong emphasis on coding (rather than low-code) covering not just Java but .Net languages such as C#, Node, JavaScript, and so on. There is some content overlap here with the Architectural Center, where Architecture Centre provides reference solutions.
Developer relations lead, which covers not only Oracle products but also the application of open source. By its very name, there is a strong emphasis on coding (rather than low-code) covering not just Java, but .Net languages such as C#, Node, JavaScript, and so on. There is some content overlap here with the Architectural Center, where Architecture Centre provides reference solutions.
This is the Architecture Center which provides reference solutions. But these aren’t exclusive to the SaaS products (which would be easy to interpret). A lot of examples cover deploying and running open-source solutions on IaaS, for example, Drupal, WordPress, and Magento to name just a couple. A lot of these are backed up with scripts, Terraform, and code to achieve the deployment and configuration. In addition to this, there are use cases of what customers have deployed into production (known as built and deployed).
This contains a lot of free tutorials and labs that can be taken a run to implement different things, from deploying a Python with Flask solution on Kubernetes to Creating USB Installation Media for Oracle Linux with Fedora Media Writer. As you can see from these examples, the tutorials cover both Oracle products and open source. These resources interlink with the Architecture Centre and can overlap with developer.oracle.com.
This contains the code artifacts developed by Developer Relations and the Architecture Center team. So covers Reference Architectures, tutorials, and Live Labs all freely available to use.
This provides a catalog of links to the various open-source repositories available. This includes oracle-sample and devrel but also the many other projects including, but not limited to Helidon, Fn, Verrrazano, GraalVM, Apiary
This is really for the educational community (Universities, Colleges & Schools) and provides resources to take you from zero to certified skills for Java and Oracle Database.
This provides a catalog of links to the various open-source repositories available. This includes oracle-sample and devrel but also many other projects including, but not limited to Helidon, Fn, Verrrazano, GraalVM, Apiary
YouTube training videos. With multiple channels based on different technologies.
Java (OpenJDK and Oracle JDK)
A number of Oracle open-source projects have their own independent web resources as well. Helidon includes additional technical resources. The ones we know more about are : Helidon, Fn, Verrrazano, GraalVM, Apiary But it includes references to Java core language etc.
Managed by Jurgen Kress (Prod Mgr for Oracle PaaS). It acts as an aggregator for contributions from the community and shares news about what is happening within Oracle to support customers and partners in the PaaS space.
Perhaps not access usable as documentation, how-to, etc. but Podcasts can yield a lot of broad picture insights. Oracle has a range of podcasts covering a diverse range of subjects. Not all podcasts are active at any one time. But the site provides a catalog and episode list.
Low level aka detailed design documentation has been an interesting point of debate. We range from the agile manifesto which states focus should be on working code over documentation and people using this as an argument for not producing documentation. On the other end of the spectrum as someone working for a large SI, documentation is more often than not contractually binding and accurate docs are key when taking work from a different supplier organization.
It is clear that documentation is an essential element. But I do agree with the agile manifesto, a business operates on its software, not documents, although the docs help us keep the software maintained and running.
How do we balance the age-old conflicts of …
Documents get out of date because they are kept separate from the implementation
Documents, particularly when rushed don’t provide the information necessary
Document templates having sections used a tickboxes rather than guide rails
Making sure we’re working with the most upto date document
Possibilities
One of the key issues for documents getting out of date is a compound issue of accessibility, visibility and ease of maintenance. These compound to separate the documentation from the reality of code and configuration.
This can be eased by bringing documentation to being ‘physically’ closer to the code as we often see with readme markdown files on GitHub for example. But we can get closer with quality code commenting, particularly for each package and module. Just about every code or notation format had its own document generator from well-proven Javadoc to Terradoc for Terraform. To illustrate my point here are a couple of examples:
If done well the documentation can be generated and deliver the right information. It would mean in structured change management the change task for the code includes the documentation. The ideas behind combining code and documentation can be seen with good API Blueprints.
When you still need to produce publishable documents, you have the opportunity to stitch multiple class and package generated docs together using tools such as pandoc. Arguably it would be the developer’s job to establish the pandoc configuration file (Documentation as Code).
You can add to this if done carefully, by adding diagrams such as UML representations. Importantly this process can generate representations that include lots of detail that would be noise to the key representation (time for tools like Sparx to support annotations that can give hints as to what to show in a generated model).
Pitfalls
The biggest risks of this approach are:
People paying lip service to documenting code, or using the argument that agile means no documentation (an age old misrepresentation).
Comments reflect the code correctly
Assuming the documentation will be clear because it is writte6x n
These pitfalls could be in theory be addressed through some smarts such as comparing the volume documentation generated against the number of lines of code and code complexity metrics.
But like many things, good culture and good application of principles are essential.
Exploring further
There are growing dedicated resources in this space, check out:
The last week or two I have been working on a new API Platform utility to add to my existing tools (see here). This tool addresses the question of generating documentation. Much as been said about API documentation and the quality of it, check out these articles :
If you look at these articles and others, there are some common themes, which are:
Document the URI / payload
Describe error handling
Describe contracts such as how many API calls
How the API is authenticated
Apiary covers the first theme to a first class standard, and you will see Apiary called out for its ability to document APIs in a lot of articles. Well written API Blueprints will cover the bulk of the second bullet. But the other points tend to fall outside of a Blueprint and fit more the API Policies and their use.
Not everyone is so commited or enjoys writing documentation. The other driver for going beyond the use of Apiary is that some organizations feel the need to have a traditional word style document to capture/define an API’s contract in detail. With the API Platform the management portal enables an API to be published into the developer portal with the Apiary definition and a markdown file for further documentation.
I came across this tweet from Oracle Developers (Oracle Developers Tweet) which picked up on a post from the NoBugsProject about common errors with the use of exceptions. One of the first errors the article described is one of my pet hates – the use of standard exceptions for application specific errors.
This took me onto one of my other pet hates – code without any documentation. I’m not advocating the days of waterfall Development where reams of documentation had to be produced before a single line of Code was written. In fact this is in my option worse than nothing as the docs would often not match the coded reality. But I absolutely agree with the agile manifesto statement:
We value working code over documentation
This doesn’t say no documentation, despite the fact that I have encountered more times than I care to recall the use of this statement to justify not documenting code. So what is the right balance?
We want to save effort from Code reviews and get clean code by using static code analysis but it doesn’t have the ability to apply smarts as what needs documenting? Pair programming is rarely practised, and there is plenty of psychology about group behaviour that can undermine documentation in a pair working approach effort. So what is the answer?
Well, I’ve always applied a couple of personal rules of thumb that can be measured with static code analysis particularly if you use conventional documentation tags. The rules are:
Interfaces warrant an interface level description of the interface purpose. It’s always helpful to describe/illustrate with use example. This is code equivalent to a good API Blueprint or swagger doc.
Provide a class level description of what the class is for – if it is a DAO then just say what the entity is.
If a class is part of a pattern, name the pattern. This is most important when relating to supporting a composite or solution pattern. Remember there will always situations where a newbie will get asked to extend or change your code, help them. Remember not every developer is as experienced or clever as you. If in doubt, give your code to someone who doesn’t know what you’re working on and ask them to explain what your code is doing and why. I had once, had to create a JDBC abstraction layer as we needed to support multiple databases. But if you know JDBC you’ll be aware of there are some subtle but important differences in implementation of connectors. I took the time to explain it in the interface header. I know a couple of developers appreciated the investment of 5 minutes.
If you have a function that has a code analytics score such as cyclometeric then describe the function. Use the comment to convey why the high score is justifiable.
If the code has specific dependencies or has to perform in a very specific sequence a short comment will help, and anyone going through refactoring code.
With these guidelines it becomes possible to then use javadoc tools to generate your documentation. It doesn’t require you to go find a word document or a wiki page to update the documentation. Of course then reviewing the generated documentation will soon help you finesse the process of documenting in a manner that is whilst light also supports readability without needing the code.
For those, who still disagree I would say …
Do you want to be maintaining and updating the same code for the rest of your career to meet new minor changes etc?
Not everyone is a great coder like you, do you want someone less capable who may have to make a change messing up your elegant code?
Sooner or later someone will ask you to fix or enhance some code that in your eyes is a chaotic unintelligible mess, I’m sure you’d appreciate some comments that will help you understand what the developer was trying to do? We can’t expect those not so good at the craft to document if the best of us are not prepared to do so.
If you don’t agree, or have found different approaches that ensure enough accurate documentation, please share.
Phil (aka MP3Monster)'s Blog 
You must be logged in to post a comment.