Find orphaned documents (automatically) and decide what to do with them about docs HOT 34 CLOSED

Some docs we've worked on (like assertions and mocking-and-stubbing) can go under "Guides"

from docs.

I wonder whether we could incorporate the HTMLProofer ruby gem into the build pipeline, or use something built for Hugo?

from docs.

As of 93c8dfa orphaned pages are printed at the end of make htmlproofer. The presence of orphans doesn't fail the build - it just prints them. There are currently 45 orphans. For each one of the orphan pages we should do one of the following:

• Move its content to an existing (linked) file
• Add a link in the nav
• Remove the page altogether

from docs.

Yes, completely agree with those suggestions. In the mean time I might park the ones I'm unsure about in a separate folder.

from docs.

If I recall correctly, most of the implementation pages are just links to GitHub projects? So can easily be consolidated into a single page.

from docs.

@plaindocs true, but then we'd need to find a place for that page
For now, we discussed to focus on the most used implementations, so imho we could park the others before go live

from docs.

@aslakhellesoy I think we might need to reconfigure a little bit. Some of the docs listed are linked to from other pages, for instance:
https://cucumber.netlify.com/cucumber/state/
links to public/implementations/jvm/java-di/index.html

from docs.

See also: #25

from docs.

Some of the docs listed are linked to from other pages

@plaindocs and I had a chat about this, and we agreed on the principle that all internal pages should be reachable from the nav. Otherwise it might be too hard to find stuff.

To avoid an explosion of links from the front page, this means some pages will have to be quite long, but I think that's fine, as long as we have a good TOC for them.

from docs.

Yeah, that sound good! I can work on it this evening.

from docs.

I think we can add Implementations to the Cucumber menu. And then put all or most of that content in a single page.

from docs.

@plaindocs will do. Also want to add "Checking assertions" to Guides (DONE)

from docs.

Working on the implementations over in #120

from docs.

Merged TDD into BDD (DONE)

from docs.

Updated list:
7:45:24 AM: === Orphaned pages ===
7:45:24 AM: public/implementations/php/index.html
7:45:24 AM: public/implementations/jvm/index.html
7:45:24 AM: public/implementations/ruby/sinatra/index.html
7:45:24 AM: public/implementations/ruby/debugging/index.html
7:45:24 AM: public/implementations/ruby/console-colours/index.html
7:45:24 AM: public/implementations/ruby/fixtures/index.html
7:45:24 AM: public/implementations/ruby/rake/index.html
7:45:24 AM: public/implementations/ruby/calling-steps-from-step-definitions/index.html
7:45:24 AM: public/implementations/ruby/ruby/index.html
7:45:24 AM: public/implementations/ruby/ruby-on-rails/index.html
7:45:24 AM: public/implementations/ruby/minitest/index.html
7:45:24 AM: public/implementations/ruby/custom-formatters/index.html
7:45:24 AM: public/implementations/ruby/browsers-and-transactions/index.html
7:45:24 AM: public/highlight/index.html
7:45:24 AM: public/cucumber/build-tools/index.html
7:45:24 AM: public/cucumber/cucumber.yml/index.html
7:45:24 AM: public/cucumber/wire-protocol/index.html
7:45:24 AM: public/cucumber/step-argument-transforms/index.html
7:45:24 AM: public/cucumber/environment-variables/index.html
7:45:24 AM: public/cucumber/editors/index.html
7:45:24 AM: public/architecture/execution/index.html
7:45:24 AM: public/admin/index.html
7:45:24 AM: public/wiki/autotest-integration/index.html
7:45:24 AM: public/wiki/a-whole-new-world/index.html
7:45:24 AM: public/wiki/cucumber-backgrounder/index.html
7:45:24 AM: public/voting/index.html
7:45:24 AM: public/step-reuse/index.html

from docs.

@aslakhellesoy Where should build tools and editors go?

cucumber.yml and environment-variables could be merged into cucumber.md? (under configuration?) - I don't know enough about either

from docs.

Since calling-steps-from-step-definitions is considered an anti-pattern (and that's the only place it's linked to), should we delete it? It also contains information on "Multiline step arguments" that may or may not be relevant elsewhere. Since it's a Ruby feature, I'll leave it for others to decide.

from docs.

/implementations/ruby/custom-formatters/ is linked to from cucumber.md - Also a Ruby feature. Should it be merged or deleted?

from docs.

wiki/autotest is linked to from content/about/related-tools.md - Also a Ruby feature. Should it be merged or deleted? (Note: this is the only doc listed in #25 that is currently linked to)

from docs.

Where should build tools and editors go?

Let’s create a tools.md page with a h1 for each category of tools (build tools, editors)

from docs.

Sounds good! (working on it) DONE

from docs.

@aslakhellesoy What is highlight.md for and do we still need it?

from docs.

@aslakhellesoy What is your intention with step-reuse.md?

from docs.

I've moved all of the unlinked orphans (i.e. docs that are not linked to from other docs) to folder _orphans; imho these docs do not need to be reviewed before GoLive.

from docs.

highlight.md is probably just a test for tweaking the code highlighting - can either be deleted or moved to the theme dir.

from docs.

If not needed anymore, let's delete?

from docs.

I think so.

from docs.

Updated list of orphans

Notes:

• I've marked the docs that are linked to from pages that are currently active (i.e. accessible from the menu) => these should be reviewed before GoLive
• Everything in "_orphans/" is not linked to from other pages.
• Everything else does link to each other internally (so I didn't move them to "_orphans" because that would break the links), but not from active pages.

11:27:11 AM: === Orphaned pages ===
11:27:11 AM: public/cucumber/environment-variables/index.html
11:27:11 AM: public/cucumber/cucumber.yml/index.html
11:27:11 AM: public/wiki/autotest-integration/index.html => linked to from related-tools.md UPDATE: Removed from related tools
11:27:11 AM: public/wiki/a-whole-new-world/index.html
11:27:11 AM: public/admin/index.html => What's this for?
11:27:11 AM: public/_orphans/architecture/execution/index.html
11:27:11 AM: public/_orphans/implementations-php/index.html
11:27:11 AM: public/_orphans/voting/index.html
11:27:11 AM: public/_orphans/cucumber-backgrounder/index.html
11:27:11 AM: public/_orphans/wire-protocol/index.html
11:27:11 AM: public/_orphans/ruby/fixtures/index.html
11:27:12 AM: public/_orphans/ruby/minitest/index.html
11:27:12 AM: public/_orphans/ruby/console-colours/index.html
11:27:12 AM: public/_orphans/step-argument-transforms/index.html
11:27:12 AM: public/_orphans/step-reuse/index.html
11:27:12 AM: public/implementations/ruby/custom-formatters/index.html => linked to from cucumber.md UPDATE: Unlinked
11:27:12 AM: public/implementations/ruby/sinatra/index.html => linked to from related-tools.md REMOVED (project was archived by owner)
11:27:12 AM: public/implementations/ruby/ruby-on-rails/index.html => linked to from tools.md and related-tools.md UPDATE: Removed links. Content should be merged?
11:27:12 AM: public/implementations/ruby/debugging/index.html
11:27:12 AM: public/implementations/ruby/calling-steps-from-step-definitions/index.html => linked to from anti-patters.md UPDATE: Unlinked
11:27:12 AM: public/implementations/ruby/browsers-and-transactions/index.html
11:27:12 AM: public/implementations/ruby/rake/index.html
11:27:12 AM: public/highlight/index.html => if not needed, let's delete? DONE

from docs.

highlight.md is indeed a test page that should be deleted

from docs.

Done ;)

from docs.

If I understand correctly, autotest is part of zentest, which was last updated almost 2 years ago on Jun 13, 2016 - Is it still used, or can it be deleted? In the mean time, I've removed zentest/autotest from related-tools, but cannot move it to "_orphans" as cucumber.yml also links to it.

from docs.

Sinatra has been archived by owner, so I removed the link from related-tools as well as implementations/ruby/sinatra.md in this commit

from docs.

Maybe related-tools.md could use a review/update to see if it contains other tools that might be outdated?

from docs.

Closed, moved to #130

from docs.