Kill TOC anchors in FAQ on website

[erget]

The FAQ has a TOC that looks like a pain to maintain because

• It's not autogenerated, so if we add a new FAQ, you have to add an entry to the TOC
• The questions also have HTTP anchors that are manually created and have to be synced to the TOC

So lots of room to mistype and forget stuff. I propose removing the whole shebang - users can scroll through the site easily enough.

Any objections? @JonathanGregory chime in if you've got an opinion.

[JonathanGregory]

It's quite common to have a table of contents for FAQs and I think it's useful to retain. I agree, it's a potential problem for maintenance. Presumably there aren't any clever ways you can autogenerate a ToC in markdown, are there? It wouldn't be hard to write a bash script or python program which processed the markdown to do it; does GitHub have hooks for processing markdown files when they're updated? Alternatively, if we converted the FAQ to AsciiDoc, could it be done automatically?

In principle I would like to spend some time adding things to the FAQ, but there has not been time. Whenever a familiar question comes up again, we should remember to add it to the FAQ.

[erget]

I think converting to AsciiDoc would be the easiest thing to do here, but then we'd need to incorporate the build into the website deployment process. You could write a script that generates the TOC, but then that would have to be maintained...

On a separate note, we did note in today's discussion that it would be useful to refer to external data discovery standards in the FAQ (it's noted in the minutes). Are you keen on taking that on? Might be an opportunity also to prune the questions as well, if any are outdated.

[JonathanGregory]

I could convert the FAQ to AsciiDoc, at the same time reviewing its contents, if you, or some other wizard, can automate its deployment on the website.

I think it's a good idea to explain in the FAQ about data discovery standards, since this certainly is a FAQ, but it's not something I know much about. Is there someone else with that expertise?

[erget]

Hi @JonathanGregory , if you're happy to do the conversion wizardry I'm happy to at least coordinate the deployment if not do it myself. Assigning you with my thanks - ping back when you need a hand or are ready for review!

[ethanrd]

I agree that TOCs are handy in FAQs. I worry that having one AsciiDoc file in a repo that otherwise has all Markdown files could be confusing and/or harder to maintain.

Also, I think there are ways to generate TOCs in Markdown. Actually, just found a StackOverflow question on TOCs in Markdown that says adding {:toc} to the top of a page will autogenerate anchors for each header and insert a TOC at the location the {:toc} is inserted.

[erget]

Apparently GitHub does this when rendering on the platform - that's neat.

I just implemented that change in faq.md but I don't think GitHub groks that, so we won't see it until it's rendered on the website (we've got _config.yml setup right so it should work AFAIK but can't test from here.

[JonathanGregory]

That's good about the FAQ ToC. Thanks, @ethanrd and @erget. Are you making a pull request for this?

[erget]

@JonathanGregory yes, the linked PR implements these changes. It also pulls in changes from #276 that is yet to be merged, but they should be pulled in sequentially. #276 is only code styling so I'd need somebody to have a glance over those before merging (@davidhassell , would you have a few seconds to have a look?).

[erget]

Thanks @davidhassell . I've just merged this whole shebang - #276 and this one, #281 - whereas I had intended to merge only #276. Oops. Was trying to take advantage of some merge conflict solutions I'd made on this branch...

I can revert that if desired, but I think we had implicit agreement on those changes and thus I invite all those interested (@ethanrd @JonathanGregory here's a ping) to review the results online. If you're not happy with this already being merged, please re-open this and I will revert in a flash and restart the conversation. These changes are IMO of a cosmetic nature and I'm happy with the result but had intended to merge the TOC-related changes only after explicit agreement, which we had not reached on the level of the PR yet.

[JonathanGregory]

The FAQ looks fine to me, @erget. Thanks for doing it. There seems to be an unnecessary level in the ToC, since the first entry "Frequently Asked Questions (FAQ) about the CF Conventions" has no contents.

[ethanrd]

Looks like kramdown (cheatsheet) has some ways to control what is included in the TOC. Just tested adding {:.no_toc} on it's own line below a header and it was excluded from the TOC.

I'll put up a PR shortly adding the no_toc to the top header.

[ethanrd]

OK. I just put up PR #295. I marked the two top-level headers to be ignored. So the TOC should only include the category headers and the question headers. I'm going to reopen this issue and link the PR.

I also re-added the summary text for some of the categories. It was part of the old TOC, I added it to the actual text. Not sure we need it but also wasn't sure whether it got removed intentionally or not. Thoughts?

Also noticed that the last section, "Maintaining the CF standard", needs some serious updating to bring it into the GitHub era. Or needs removing or to be replaced with a pointer to CONTRIBUTING.md and/or rules.md.

[erget]

@ethanrd thanks very much, that is ace.

[JonathanGregory]

Thanks @ethanrd from me too.