-
Notifications
You must be signed in to change notification settings - Fork 123
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Deduplicate plugin documentation #1256
Comments
My PoV is that I don't like stories :) So docstring for me is better, it is closer to the code. |
Since we have "dreams" and "ideas" in specification - it could be messy in --help or require additional logic to remove not implemented but planned stuff happening in steps/tmt |
On the other hand - we are likely to have images, tables, links and extended examples in 'docs' while having more concise --help. |
Another thing to improve is structure of docs - some plugins are huge, specification is mixing plugins for how with step properties, etc. |
Yeah, we could also make use of the title attribute to make the headings more readable. |
I somehow missed this issue, but I believe that I've been working towards solving it for a couple of months already. I agree with the points discussed above, namely the mixture of specification and plugin docs. My approach is this:
What I have so far:
|
Currently we store detailed plugin documentation at two places:
The first is used to generate web docs, the second for the
--help
message. The content is very similar though. Would be nice to find a way how to maintain this at once place only. Quick brainstorm:click
?The specification should always be a starting point so I'd say the first approach probably makes more sense. Any other way? Thoughts?
The text was updated successfully, but these errors were encountered: