Investigate the documentation automation space

[ForestEckhardt]

There is a desire to have reference documentation for the buildpacks that is automatically generated from the buildpacks themselves. This would allow the Paketo website to have the most up-to-date documentation regarding the features of the buildpack with little to no burden on the maintainers of either the buildpack or the website to keep constantly updating them.

However, before a full scale implementation is planned and worked on, we would like to get a lay of the land of the current documentation automation space. This will allow us to get a better understanding a couple of things:

• What do people expect from automated reference documentation?
• What is possible in automated documentation?
• What tools are at our disposal?
• What are good and bad automated documentation practices?
• Is there an existing solution that solves our problem or do we need to combine solution or do we need to go completely bespoke?
• What information already exists in a parsable format in our buildpacks?
• What information could be added to our buildpacks with little to no effort?

The acceptance criteria for this investigation is to try and answer as many of these as possible and document our findings on this issue. To keep us focused and limit our sprawl, we will mostly likely time box this issue to 2 days and then report our final conclusion and close the issue. Further investigations will most likely result in a standalone issue.

[ForestEckhardt]

After some investigation I think I have come to a couple of strong conclusion on both what should be present in reference documentation as well as the ways of going about autogenerating said documentation. Divio has done some incredible work laying out a solid structure for software documentation and I think that it is a format worth following as close to the letter as possible. For an exact outline of what they expect from reference documentation you can check out their write up here but I strongly encourage you to give the whole site a read as I feel that it is extremely informative and well through out. This lays out the general idea of what should be contained inside of reference documentation which is something that I think we can refine with Paketo specific convention.

As for the actual content and structure I think that I have come to the understanding that the interface point needs to be easily understood so that it can be approachable from someone with little to no knowledge of the codebase. It should be intuitive how to how reference documentation as part of the process of adding a new feature. So ultimately we need to either reduce or completely eliminate the amount of magic that our automation is doing and make it very clear to our contributors what will end up in the reference documentation once it is generate and how it will look.

On the topic of existing solutions, the only major existing solution for Go is godoc. I think there are some reason why I would like to preserve both a godocs set of reference documentation as well as autogenerated documentation that end up on the Paketo website. I think at the end of the day by separating and maintaining both you better serve two separate user bases. godocs I feel is better suited to buildpack developer that is either trying to develop for the buildpack itself or one that is trying to integrate into the buildpack in question. I don't feel that this kind of documentation would server a buildpack user in the same way so I feel that some unique documentation needs to be generated for this user.

---

I think to give a quick TL;DR Divio's outline on reference documentation what we will be using as our north star but we will be adding Paketo specific conventions to help steer ourselves to project uniformity. How to add reference documentation should be relatively obvious to even an outside contributor and there should be as little magic/inside knowledge needed to understand the docs generation.

[ForestEckhardt]

I think there are a couple of interesting solutions that we could look into that I am going to document here for discussion and completeness sake.

Environment Variable Reference

The adoption of the environment variable configuration table that is used by many buildpacks in the Java language family is an ideal solution to allow for the automatic generation of documentation around what environment variables the buildpack can and does set:

[[metadata.configurations]]
name        = "BPL_JMX_ENABLED"
description = "whether to enable JMX support"
launch      = true

[[metadata.configurations]]
name        = "BPL_JMX_PORT"
description = "what port the JMX Connector will listen on"
default     = "5000"
launch      = true

[[metadata.configurations]]
name        = "BP_JMX_ENABLED"
description = "whether to contribute JMX support"
build       = true

We could write tooling to parse these fields and add them to other reference documentation.

Additional Reference Documentation

I have been thinking about two different ideas with how to add custom pieces of reference documentation.

Docs file

Add a general docs.md or even docs.go file to the base of the repository. Any additional reference documentation can be added to this document and then using additional tooling it can be combined with other autogenerated documentation.

Pros

It is extremely obvious to an outside user where to add new reference content and how that will be rendered once the documentation is generated.

Cons

It divorces the reference context from the code that it is about meaning that you may end up having duplicate documentation in the form of context in the docs file as well as comments left in the code.

Tagged Comments

Add the ability to tag code comments as comments that should also be added to the reference documentation.

func main() {
  some code
  // DOCUMENTATION: This will go in the reference documentation
  more code
}

Pros

The code and the documentation are intertwined making them useful for both a buildpack author as well as a buildpack user.

Cons

The documentation is spread out and it is not immediately obvious to a new contributor how to add new documentation to the reference documentation or how it will be formatted.

[ForestEckhardt]

We will spin up an RFC to propose a new reference documentation automation structure.