• Home
  • Site Aliases
    • www.cloud-native.info
    • oracle.cloud-native.info
    • Phil-Wilkins.uk
  • About
    • Background
    • Presenting Activities
    • Internet Profile
      • LinkedIn
    • About
  • Books & Publications
    • Logging in Action with Fluentd, Kubernetes and More
      • Logging in Action with Fluentd – Book
      • Fluentd Book Resources
      • Log Generator
    • API & API Platform
      • API Useful Resources
    • Oracle Integration
      • Book Website
      • Useful Reading Sources
    • Publication Contributions
  • Resources
    • GitHub
    • Mindmaps Index
    • Oracle Integration Site
    • Useful Tech Resources …
      • Oracle Tech Resources inc Open Source
      • Useful Tech Resources
      • Python Setup & related stuff
  • Music

Phil (aka MP3Monster)'s Blog

~ from Technology to Music

Phil (aka MP3Monster)'s Blog

Tag Archives: documentation

Knowledge Resources from Oracle

05 Tuesday Apr 2022

Posted by mp3monster in Cloud, General, Oracle, Technology

≈ Leave a comment

Tags

documentation, knowledge, Oracle, resources

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 …

Domain AddressDescription
oracle.comThis is the commercial side of the Oracle content. But includes a landing page for a lot of Oracle knowledge/documentation.
docs.oracle.comThe home of the core Oracle documentation for all products.
blogs.oracle.comOracle blogs primarily from Oracle staff covering different parts of the organization, covering employment diversity through to each of the major product families, domain verticals such as Retail, Hospitality. The blogs are broken into groups, so it’s worth bookmarking the product groups of interest, for example, Infrastructure.
In addition to the product spaces, there are blogs that come from teams such as the A-Team – Infrastructure, Java Magazine,
A-TeamThe members of this team are the ‘gurus’ of product application. 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.oracle.comDeveloper 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.
docs.oracle.com/solutions
(AKA Architecture Center)
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).
docs.oracle.com/learn/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.
github.com/oracle-devrelThis 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.
github.com/oracle-samplesThis repository contains example solutions and Terraform logic developed by groups such as the A-Team.
opensource.oracle.comThis 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
community.oracle.com/hubThis is where a lot of the Q&A for Oracle Partners and users takes place. Community participation is gamified to encourage participation.
academy.oracle.comThis 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.
education.oracle.comPrimarily for the formal Oracle certification resources, but there are some free training resources here as well.
apex.oracle.comAPEX has its own area of dedicated resources. This includes solutions, templates, and other development resources, and community.
github.com/oracleThis is the home for the majority of all Oracle free code, including the Open source projects such as Helidon, JET, Kubernetes Operators, and so on.
Helidon, Fn, and other source projectsA 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
Bit it includes references to Java core language etc.
www.youtube.com/oracleYouTube training videos. With multiple channels based on different technologies.
Java (OpenJDK and Oracle JDK)Oracle propel not just their main JDK /JRE which has license constraints, but also Open JDK. With this comes a dedicated Developer zone as dev.java.
PaaS CommunityManaged 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.
Developer CommunityPartner site to the PaaS Community with a focus on more development activities around Weblogic, Helidon, etc.
LunaTutorials etc relating to the use of Linux and related Cloud Native things such as Verrazano, OCNE (Kubernetes) etc.
Oracle PodcastsPerhaps 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.

Share this:

  • Twitter
  • Facebook
  • LinkedIn
  • Print
  • Pocket
  • Email
  • Tumblr
  • Reddit
  • Pinterest
  • WhatsApp
  • Skype

Like this:

Like Loading...

Detailed (Low Level) documentation

10 Friday Dec 2021

Posted by mp3monster in development, General, Technology

≈ Leave a comment

Tags

code, development, documentation

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:

  • https://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html
  • https://ruby-doc.org/stdlib-3.0.3/libdoc/observer/rdoc/Observable.html

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:

  • https://idratherbewriting.com/
  • https://swimm.io/

Share this:

  • Twitter
  • Facebook
  • LinkedIn
  • Print
  • Pocket
  • Email
  • Tumblr
  • Reddit
  • Pinterest
  • WhatsApp
  • Skype

Like this:

Like Loading...

Documenting APIs on the Oracle API Platform

21 Monday May 2018

Posted by mp3monster in API Platform CS, General, Oracle, Technology, tools

≈ 2 Comments

Tags

API, API Platform, documentation, Groovy, tool, utility

Updated reflecting changes discussed in blog post:
Making Scripts Work with IDCS Deployed PaaS

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 :

  • https://nordicapis.com/the-easiest-ways-to-generate-api-documentation/
  • https://dzone.com/articles/best-practices-in-api-documentation

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.

Continue reading →

Share this:

  • Twitter
  • Facebook
  • LinkedIn
  • Print
  • Pocket
  • Email
  • Tumblr
  • Reddit
  • Pinterest
  • WhatsApp
  • Skype

Like this:

Like Loading...

No documentation – a coding error?

01 Friday Dec 2017

Posted by mp3monster in development, General, Oracle

≈ Leave a comment

Tags

coding, development, docs, documentation, error, NoBugsProject

Documentation

from http://geek-and-poke.com

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.

Share this:

  • Twitter
  • Facebook
  • LinkedIn
  • Print
  • Pocket
  • Email
  • Tumblr
  • Reddit
  • Pinterest
  • WhatsApp
  • Skype

Like this:

Like Loading...

Aliases

  • phil-wilkins.uk
  • cloud-native.info
  • oracle.cloud-native.info

I work for Oracle, all opinions here are my own & do not necessarily reflect the views of Oracle

Oracle Ace Director Alumni

TOGAF 9

Logging in Action

Oracle Cloud Integration Book

API Platform Book


Oracle Dev Meetup London

Categories

  • App Ideas
  • Books
    • Book Reviews
    • manning
    • Oracle Press
    • Packt
  • Enterprise architecture
  • General
    • economy
    • LinkedIn
    • Website
  • Music
    • Music Resources
    • Music Reviews
  • Photography
  • Podcasts
  • Technology
    • APIs & microservices
    • chatbots
    • Cloud
    • Cloud Native
    • Dev Meetup
    • development
      • languages
        • node.js
    • drone
    • Fluentd
    • logsimulator
    • mindmap
    • OMESA
    • Oracle
      • API Platform CS
        • tools
      • Helidon
      • ITSO & OEAF
      • Java Cloud
      • NodeJS Cloud
      • OIC – ICS
      • Oracle Cloud Native
      • OUG
    • railroad diagrams
    • TOGAF
  • xxRetired

My Other Web Content & Contributions

  • Amazon Author entry
  • API Platform
  • Dev Meetup (co-managed)
  • Fluentd Book
  • ICS Book Website
  • OMESA
  • Ora World
  • Oracle Community Directory
  • Packt Author Bio
  • Phil on Blogs.Oracle.com
  • Sessionize Profile

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Join 2,541 other subscribers

RSS

RSS Feed RSS - Posts

RSS Feed RSS - Comments

February 2023
M T W T F S S
 12345
6789101112
13141516171819
20212223242526
2728  
« Jan    

Twitter

  • File system replication is now available as a fully managed solution for your enterprise workloads with #OCI File S… twitter.com/i/web/status/1…Next Tweet: 4 days ago
  • Find out how NIBIO's Smart Forest research center utilizes @OracleCloud to store, process, and apply #AI to data to… twitter.com/i/web/status/1…Next Tweet: 5 days ago
  • .@TechArena's latest ebook "Seven Strategies for Maximizing Organizational Return” highlights #OCI. Bev Crair discu… twitter.com/i/web/status/1…Next Tweet: 5 days ago
  • Clever use of SSH tunnelling, Applies to multiple Linux flavours and Windows .... blogs.oracle.com/developers/pos…Next Tweet: 5 days ago
  • 25% done with Let's Do It, by Bob Stanley goodreads.com/user_status/sh…Next Tweet: 6 days ago
Follow @mp3monster

History

Speaker Recognition

Open Source Summit Speaker

Flickr Pics

Pembroke CastleSeven Bridge Crossing
More Photos

    Social

    • View @mp3monster’s profile on Twitter
    • View philwilkins’s profile on LinkedIn
    • View mp3monster’s profile on GitHub
    • View mp3monster’s profile on Flickr
    • View philmp3monster’s profile on Twitch
    Follow Phil (aka MP3Monster)'s Blog on WordPress.com

    Blog at WordPress.com.

    • Follow Following
      • Phil (aka MP3Monster)'s Blog
      • Join 217 other followers
      • Already have a WordPress.com account? Log in now.
      • Phil (aka MP3Monster)'s Blog
      • Customize
      • Follow Following
      • Sign up
      • Log in
      • Report this content
      • View site in Reader
      • Manage subscriptions
      • Collapse this bar
     

    Loading Comments...
     

    You must be logged in to post a comment.

      Privacy & Cookies: This site uses cookies. By continuing to use this website, you agree to their use.
      To find out more, including how to control cookies, see here: Our Cookie Policy
      %d bloggers like this: