Documentation is in a flat file structure

[WalterMoar]

The documentation in the Wiki was had all the files in one directory. This should be cleaned up and organized into a tree of directories that are organized in some logical way.

Definition of Done:

• Create a Style Guide
• Add a file naming convention to the Style Guide and strictly follow it
• Organize all files reachable from the nav or index.md into a tree file structure
• Figure out what to do with files not reachable from the nav or index.md (include or delete)
• Ensure that all links between files are updated and working correctly, including breadcrumbs

[matthewhall78]

I'm concerned that creating the hierarchy might make more work to maintain links. Isn't there value in having a flat structure? Just a thought.

[WalterMoar]

Yes, if we move to a tree structure then if a page was moved from one directory to another it would break links and bookmarks to that page. I guess the question is: how often will we be re-organizing things once we have it organized.

One problem we have right now is that there are "orphan" pages in the docs directory that aren't reachable through the table of contents or links in the pages. There's no way of knowing what pages these are, though, without searching for each one within the links. If we had a tree structure, then there's be fewer pages in each directory and I think (?) it would be easier to track down orphaned pages. We could also move examples and page-specific images into the directories, as we have the same problem with the images: which ones are actually being used, and which ones have been "lost"?

So yes, "it depends"!

[vijaivir]

I have arranged the files in the structure currently implemented in the GitHub wiki. I think the organization of the file structure can be improved but that work might require some further research and involving our UX and service designers. For now, we can push the docs to the production environment while the details of the file structure are finalized.