| I set up a prototype for `command run`. Partial screenshot shown:
 (I'm not leaving this live in the preview docs because it will get pushed to production automatically when we release.) This layout seems like a big improvement over the current model. However, the timing to implement this change is tricky. We're currently reconsidering how we handle Bolt docs, so I'm not sure if makes sense to make this formatting change in the GitHub pre-docs, our docs source, or both. If it's possible to hold off on making this change until we have a clear path forward for managing Bolt docs source, that would probably save time in the long run. Michelle Fredette This mocked-up topic is command_run.dita in the Bolt dev branch. If we decide to continue building Bolt docs from DITA source, from a technical standpoint, it makes sense to break up the command reference this way. The existing setup has the entire command reference in a single topic, and it's too much for easyDITA, causing the topic to bounce around in editing mode, etc. I envisioned single-sourcing the options in the tables. Potentially, you could duplicate the existing command reference topic and use it as a new conref topic, wrap the contents of each table cell in <ph> elements and assign IDs, and then conref the <ph>s into command topics as needed. If you need an example: the PE port requirements tables are set up similarly. This sounds like some work, but it will be much easier than maintaining separate options references for each command. |
