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.