Documentation strategy for this repo going forward.

[hsyed]

Skydoc had a lot of problems and was becoming a major hinderance for this repo so it has been removed. A new documentation tool is in the works. I don't have any details for this but I think I will use it once it is available.

A lot of the internal and public elements of the rules are already documented but it is outdated. I suspect the new tool will work out of the box. However, this won't be the whole solution, design docs , usage tutorials and faqs cant all be inlined and extracted from the rules.

The go rules use rst for hand written documentation. I really like this approach. I have since discovered asciidoc it is functionally equivalent to rst as a better markdown but it is easier to work with (richer intellij plugin, simpler patterns and supported by github).

I wonder what output formats the new Skydoc tool will support. It would be nice to be able to weave the extracted documentation into technical documentation that is written in markdown / rst / asciidoc. It is quite valuable to have the rule contracts documented and browse-able via github without having to go to a separate website.

I'll make a start on some asciidoc -- but I need feedback on how heavily I should invest in it as I don't know what is on the horizon. The kotlin rules need a lot of documentation for users and developers alike so it's important to get to a stable documentation strategy. If you are working on bazel core, the new tool or have any insights please give your feedback.

[hsyed]

cc @laurentlb

[laurentlb]

cc @c-parsons

[pauldraper]

The new Stardoc tool is much better than the old one.

It supports both Markdown and HTML.

I'm sure you can get superior documentation by hand, but the new Stardoc is at least reasonable.

[bradb423]

Hi there,

Is there anything still outstanding in this issue in order for it to be closed?