Skip to content
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

Improve usabilty of user documentation #1667

Open
claremacrae opened this issue Jun 24, 2019 · 1 comment

Comments

Projects
None yet
2 participants
@claremacrae
Copy link
Contributor

commented Jun 24, 2019

Request

This issue is for capturing actions arising from @horenmar 's request on Discord of 2019-06-15 "Help wanted: documentation"

The current documentation is pretty okay, but it definitely shows that it has evolved over multiple years, using different expository styles and was targeted at different audience.

And as the feature set grows, the documentation needs to become more hierarchical, and there also needs to be a split between expository, tutorialish, documentation for people who are starting out with Catch, and the reference documentation for people who are already comfortable with Catch, but need to find out e.g. customization points for generators

Also, completely separately, because the number of issues that go "Feature X does not work.", "Have you tried updating to a version where the feature actually is?" "Uhhh", the documentation probably also needs to document when a feature was introduced.

We (Clare and Martin, in discussion) have agreed we'll stick with Markdown for now and see how far we can get with improving the docs - so moving to things that need a separate rendering/processing step e.g. sphinx, Doxygen, ASCIIdoc is out of scope for this ticket

Types of user

The intention is to consider 3 categories of user:

  1. Those who have brand new to Catch - seeing the docs for the first time - who want to be guided through
  2. Advanced users who want to customise things
  3. Experts, who want a full reference

Good examples

Examples of the kind of thing wanted:

General Actions

  • #1695 For recently-added features, add "Introduced in Catch 2.x.y" to the documentation - see https://docs.gitlab.com/ee/ci/variables/#variable-types for an example
  • Find a way to give different ways to jump in to the documentation, depending on level of knowledge (See Python 3.3 example above for the kind of thing being thought of)

Pages - and actions for them

claremacrae added a commit to claremacrae/Catch2 that referenced this issue Jul 5, 2019

horenmar added a commit that referenced this issue Jul 6, 2019

@claremacrae

This comment has been minimized.

Copy link
Contributor Author

commented Jul 18, 2019

I had a look at the "Introduced in GitLab 11.11." text in gitlab https://docs.gitlab.com/ee/ci/variables/#variable-types to see how they formatted it, and if they had any automated processing.

It looks like simple markdown:

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/46806) in GitLab 11.11.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.