Should you mirror the directory structure of the application

[camerons]

Re: https://github.com/thegooddocsproject/templates/blob/master/writing-tips.md

Mirror the directory structure
If you are documenting a UI-based tool or code-base, structure the docs using the same directory structure or page tree navigation as the tool or code base.

Felicity Brand
13:37 14 Nov
Ooh, controversial! Not always a great idea. Depends on the software that you're documenting.

[mgan59]

Agreed, it depends on software.

If documenting software there are times when the docs should go inside of the folder where the code lives. There are IDE clients out there for python/juypiter notebooks that auto-generate markdown-docs. In these cases there is little control over where the docs like from a developer perspective. Especially if it is generating readmes all over the place.

Storybook and the mdx movement is another example of docs living at the node-level of the UI.

But there are times also when I prefer just a docs/ folder at the root repo level.

Let the developers writing the code/docs determine where the docs go.

[shreyas1599]

+1. I think we should just remove the line. @camerons Can I go ahead and do it?

[jaredmorgs]

Even though I wrote this original copy I agree that it isn't appropriate in our templates. This text was borrowed from work I did for another org so it was quite specific. ;)

[emckean]

fixed in PR #125