Revisit Command pages

[lornajane]

Describe the bug

We have some very mixed layout and formatting on our existing command documentation. Review all pages in the commands section and in particular look for:

• Meaningful introduction, explanation and use case for each command.
• Show examples of each task/operation rather than each parameter or value.
• Use formatting wisely, consider which segments need to be copyable (use a code block), which do not (e.g. command output), and try to keep the use of admonitions to 2-3 per page. Be extra careful with tabs: a user should be able to pick a tab and read continuously through the document. If we make people click on each tab in turn, the tabs should be removed.
• Be consistent in heading levels and using active voice for task-based headings throughout.
• Use informal but professional language, sometimes the puns can be difficult to tackle for our non-native English audience.
• Every code snippet must be preceeded and followed by explanatory text.

(follows on from our discussions in #1386 )

[dianacheung]

Hi @lornajane, I'm interested in working on this issue. This will be my first Redocly issue. Thanks!

[dianacheung]

Hi @lornajane, I'm getting an error following the instructions in the contributing guide.

To preview your changes locally, run this command from the docs/ folder:
https://redocly.com/docs/cli/

I got an error stating it is not a valid command. I couldn't find any other information in the repo or online. Please advise.

[lornajane]

That doesn't seem right at all. Try running redocly preview ?

[dianacheung]

Thanks @lornajane. Using redocly preview worked for me. Should I open an issue for contributing.md to correct the command?

[lornajane]

That would be excellent, yes please!

[dianacheung]

I have opened new bug issue #1532.

[dianacheung]

Hi @lornajane, I have questions on a couple requirements for this issue:

• "Consider which segments need to be copyable (use a code block), which do not (e.g. command output)" --> Not sure what replacement Markdown block to use though for command output that would still provide syntax highlighting and formatting. My understanding is that the copy-to-clipboard functionality is typically handled by the platform or application rendering the Markdown, rather than being a feature of the Markdown syntax itself. Managing screenshots would be even more difficult. I think keeping it as code block is sufficient.
• "Every code snippet must be preceded and followed by explanatory text." --> I think this depends on the specific code snippet. For short, simple code snippet, it is sufficient to have preceding OR following explanatory text.

Appreciate your clarifications and feedback.

[lornajane]

Good questions here:

• the commands would be better in a code block. BUT because we also have the output shown as code blocks, this creates a big page full of code blocks that is really difficult to read! Perhaps the output examples can go into <pre> tags instead, what do you think?
• agree, some text with every example would be fine. I tend to give the high-level view of what an example does before it, then follow with which bit does what, but each situation needs appropriate context, definitely.

Does that give you enough to go on?

[dianacheung]

Thanks for your input @lornajane. I have 4 commands remaining to modify. Expect a decent-sized PR in 2-3 days.

[dianacheung]

Hi @lornajane, created PR #1560. Please review and approve. Thanks.