• 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

Daily Archives: December 10, 2021

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...

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
  • 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
    • TOGAF
  • xxRetired

Twitter

  • Streaming APIs blog.mp3monster.org/2022/08/05/str…Next Tweet: 2 days ago
  • Explore the key design decisions and best practices for architecting your #OCI workload networking.… twitter.com/i/web/status/1…Next Tweet: 3 days ago
  • In this live webinar, @Oracle experts will get you started on your journey with #OCI. This is an introduction to Or… twitter.com/i/web/status/1…Next Tweet: 4 days ago
  • Working together 🤝 @lleung shares with @techcrunch how organizations running pre-cloud technology can get value out… twitter.com/i/web/status/1…Next Tweet: 5 days ago
  • Exciting news! we crossed 3 forks on our collections for @getpostman Visit postman.com/PhilWilkins/wo… to get started with our APIs today!Next Tweet: 5 days ago
Follow @mp3monster

OraWorld

OraWorld

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

Join 619 other followers

Blogs I Follow

  • Christopher's Blog
  • MiddlewarEArchitecT
  • Site Title
  • All about modern software technologies & architectures
  • Rick's blog
  • A journey in development
  • Phil (aka MP3Monster)'s Blog
  • RedThunder.Blog
  • A millennial's musings
  • Shalindra's Blogs
  • BTplusMore
  • Creativenauts
  • PaaS Community Blog
  • RedStack
  • Musings of an Enterprise Software Technologist
  • The Open Group Blog
  • SutoCom Solutions
  • Rob's Wall Of Music
  • DataCentricSec.com
  • A World of Events

My Other Web Content & Contributions

  • All My Links
  • Amazon Author entry
  • API Platform
  • Dev Meetup (co-managed)
  • Fluentd Book
  • GitHub
  • http://phil-wilkins.uk/
  • ICS Book Website
  • Mindmaps
  • Monster's Photos
  • my Capgemini Profile
  • OMESA
  • Oracle Community Directory
  • Packt Author Bio
  • Phil on Blogs.Oracle.com

RSS

RSS Feed RSS - Posts

RSS Feed RSS - Comments

Calendar

December 2021
M T W T F S S
 12345
6789101112
13141516171819
20212223242526
2728293031  
« Nov   Jan »

Other Pages

  • About
    • Internet Profile
    • Presenting Activities
  • Books & Publications
    • API & API Platform
      • API Useful Resources
      • Useful Reading Sources
    • Logging in Action with Fluentd, Kubernetes and More
    • Oracle Integration
  • Mindmaps Index
  • Useful Tech Resources
    • Oracle Tech Resources inc Open Source
    • Python Setup & related tips

Speaker Recognition

Open Source Summit Speaker

Flickr Pics

Sound InstallationSound InstallationSound InstallationSound Installation
More Photos

History

Goodreads

OraNA

Aggregated by OraNA

Blogroll

  • A Journey in Development
  • A Neate Blog
  • Amy Simpson Grange blog
  • Blog by Robert van Mölken (co-author on ICS book)
  • Developer Community
  • Exigency In Specie
  • Flexagon (FlexDepoy)
  • GitHub
  • http://phil-wilkins.uk/
  • Ora World
  • PaaS Community
  • SOA4U

Calendar

December 2021
M T W T F S S
 12345
6789101112
13141516171819
20212223242526
2728293031  
« Nov   Jan »

Categories

  • App Ideas
  • Books
    • Book Reviews
    • manning
    • Oracle Press
    • Packt
  • Enterprise architecture
  • General
    • economy
    • LinkedIn
    • Website
  • Music
    • Music Resources
    • Music Reviews
  • Photography
  • 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
    • TOGAF
  • xxRetired

Twitter

  • Streaming APIs blog.mp3monster.org/2022/08/05/str…Next Tweet: 2 days ago
  • Explore the key design decisions and best practices for architecting your #OCI workload networking.… twitter.com/i/web/status/1…Next Tweet: 3 days ago
  • In this live webinar, @Oracle experts will get you started on your journey with #OCI. This is an introduction to Or… twitter.com/i/web/status/1…Next Tweet: 4 days ago
  • Working together 🤝 @lleung shares with @techcrunch how organizations running pre-cloud technology can get value out… twitter.com/i/web/status/1…Next Tweet: 5 days ago
  • Exciting news! we crossed 3 forks on our collections for @getpostman Visit postman.com/PhilWilkins/wo… to get started with our APIs today!Next Tweet: 5 days ago
Follow @mp3monster

Flickr Pics

Sound InstallationSound InstallationSound InstallationSound Installation
More Photos

My Other Web Content & Contributions

  • All My Links
  • Amazon Author entry
  • API Platform
  • Dev Meetup (co-managed)
  • Fluentd Book
  • GitHub
  • http://phil-wilkins.uk/
  • ICS Book Website
  • Mindmaps
  • Monster's Photos
  • my Capgemini Profile
  • OMESA
  • Oracle Community Directory
  • Packt Author Bio
  • Phil on Blogs.Oracle.com

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

Join 619 other followers

History

Other Pages

  • About
    • Internet Profile
    • Presenting Activities
  • Books & Publications
    • API & API Platform
      • API Useful Resources
      • Useful Reading Sources
    • Logging in Action with Fluentd, Kubernetes and More
    • Oracle Integration
  • Mindmaps Index
  • Useful Tech Resources
    • Oracle Tech Resources inc Open Source
    • Python Setup & related tips

RSS

RSS Feed RSS - Posts

RSS Feed RSS - Comments

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.

Christopher's Blog

MiddlewarEArchitecT

Site Title

All about modern software technologies & architectures

Cloud-native, technology and software architecture

Rick's blog

End-to-End OIC to SAP integration

A journey in development

A blog-post by blog-post journey of a ERP Cloud Solutions Degree Apprentice

Phil (aka MP3Monster)'s Blog

from Technology to Music

RedThunder.Blog

Demystifying cloud technologies...

A millennial's musings

Shalindra's Blogs

Technofunctional Blogs

BTplusMore

Business, Technology and more

Creativenauts

Personal, design, inspiration, interests.

PaaS Community Blog

by Jürgen Kress

RedStack

Oracle Database and Cloud Stuff

Musings of an Enterprise Software Technologist

My thoughts on Enterprise Software Technologies...and more.

The Open Group Blog

Achieving business objectives through technology standards

SutoCom Solutions

Success & Satisfaction with the Cloud

Rob's Wall Of Music

Thoughts of a lifelong music hoarder...

DataCentricSec.com

A World of Events

A Blog for Event and Data Analytics

  • Follow Following
    • Phil (aka MP3Monster)'s Blog
    • Join 619 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
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: