Lots of directories with nothing but an index.md

[ferrouswheel]

We have some pages that unnecessarily use directories, making it annoying to edit content. In editor tabs it shows up as lots of index.md files opened.

People should use directories only if needed. e.g. there is associated content (some of the tutorials) or there is a nested structure to the content itself.

Even for associated content, I think it'd be better to keep our documentation separate from the actual scripts and code.

These guidelines should be added to #37 if agreed upon.

[IbbyBenali]

Can you maybe point to some of the unnecessary ones as an example and how you would re-organize that?

[ferrouswheel]

It's primarily the directories under tutorials. Every tutorial had a directory, even if they have no supporting assets.

My preference would be:

tutorials/[tutorial-name].md

(as I've done for tutorials/call-a-service.md etc)

Then for the actual assets (only for tutorials that provided them):

tutorials/assets/[tutorial-name]/**

This keeps the code, scripts, and other details separate from the documentation and makes it less annoying to maintain the documentation. e.g. instead of having 5 index.md files open, we'd have 5 files with distinct names.

[IbbyBenali]

The index.md gives an overview page though currently of the assets in that directory, a bit like a table of contents but then as a "boxes of contents" for the way it looks right now. Maybe when we resolve the way we want to organize our navigation we could change this as well.

[ferrouswheel]

In this case they don't... the are the tutorial itself.

Other index.md pages do give an overview and list of cards like you say, but this isn't what I'm complaining about in this instance 😜

[IbbyBenali]

Aah I see! Good catch.

…

On 21 Mar 2019, 21:17 +0100, Joel ***@***.***>, wrote: In this case they don't... the are the tutorial itself. Other index.md pages do give an overview and list of cards like you say, but this isn't what I'm complaining about in this instance 😜 — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

[ferrouswheel]

Cleaned up some of them in fe2969d

I opted to leave the tutorial directories with assets as they are, because there would be a lot of links to check and update.