Thoughts on separating both:

Current state:

1. https://docs.fastlane.tools/actions/sigh/
2. https://docs.fastlane.tools/actions/get_provisioning_profile/

Both have approx. same content: Some manual sigh docs, then the normal get_provisioning_profile action docs.

Possible future state:

1. https://docs.fastlane.tools/tools/sigh/
2. https://docs.fastlane.tools/actions/sigh/
3. https://docs.fastlane.tools/actions/get_provisioning_profile/

• 1 has the manual sigh docs, with focus about CLI usage. It has a new prominent link to 3 that explains how to use its functionality via an action.
• 2 has links to both 1 and 3 explaining that the CLI usage is via the tool, action usage via get_provisioning_profile. It is clearly "depromoted" in the list of actions as "deprecated" or similar.
• 3 does not have the tool stuff any more, but a new prominent link to 1 that mentions that setup etc is done with the tool.

Having the action docs removed from the tool page, it would enable us to add some interesting information:

• Commands list
• Parameters list (probably quite identical to that of action?)
• Configuration file

With extracted tool documentation, fastlane could get rid of the special handling of some action documentation where an additional markdown file is attached before the actual action docs. These markdown files would then be used for the new tools docs.

Notes on future maintenance: tools.md, mkdocs.yml and tools/... would have to be generated for tools similar to how currently for actions.

Relevant code:

• https://github.com/fastlane/fastlane/blob/e3afc4105988d3aaf4b2bef746f4101eeb441af9/fastlane/lib/fastlane/documentation/markdown_docs_generator.rb
• https://github.com/fastlane/fastlane/blob/665a23e6351702bbd6980fe1f7ec75a6f1f7bfa6/fastlane/Fastfile#L340
• https://github.com/fastlane/fastlane/blob/665a23e6351702bbd6980fe1f7ec75a6f1f7bfa6/fastlane/lib/assets/Actions.md.erb
• https://github.com/fastlane/fastlane/blob/13304ab7e2dcf6471f6ed4c30da96843ebf85234/fastlane/lib/assets/ActionDetails.md.erb

How could/should navigation work for tools?

• Similar to "Actions", we don't want to list all the tool names all the time.
• But when you are on the page of a tool, "Tools" definitely should be highlighted.
• As tools are not that numerous, we can even list all available tools in the navigation when on the Tools page or on an individual tool.
• When on an individual tool page, the headlines of the document can also directly be shown in the navigation.

The connected PR has most of this implemented for demonstration:

• https://deploy-preview-657--fastlane-docs-preview.netlify.com/
  New "Tools" entry in menu
• https://deploy-preview-657--fastlane-docs-preview.netlify.com/tools/
  Makeshift explanation of tools and list of tools
• https://deploy-preview-657--fastlane-docs-preview.netlify.com/tools/gym/
  Tool description (taken from current action docs)
• https://deploy-preview-657--fastlane-docs-preview.netlify.com/actions/gym/
  Deprecated action alias
• https://deploy-preview-657--fastlane-docs-preview.netlify.com/actions/build_ios_app/
  Shorter and more focused action docs

All the new content of course would need some serious improvement, and it would all probably benefit very much from an "Introduction to fastlane" article where lanes, actions, tools etc are explained.

Maybe where we talk about alias we should make it known that people aren't expected to understand aliases.
Like, Advanced fastlane users: ___ is an alias for ___

Whereas right now, we just mention what tools have what aliases. It's probably not clear to noobs that they can ignore that.

A bit OT, but: For brand new users, aliases shouldn't be relevant at all. Only for the old timers we should have some backwards compatibility available so they have the necessary context available.

I was convinced via Slack that this is not the way to go - tools are just actions.