Wiki Structure (Declined, Pending Update)

[wesleyboar]

Update: This proposal does not match the intent. It will be revisited or discarded.

I propose a structure like that of Core-Portal.

My response to Initial Home page (baef112)'s TBD points:

• Determine structure of wiki content.
  • A sidebar and this hierarchy:
    • Home (link)
    • Processes (category)
    • Instructions (category) ¹
    • Troubleshooting (category) ¹
    • (?) Proposals (category)
  • Example: Core-Portal/wiki ¹
• Identify which procedures and policies to document in the wiki vs in the repository docs section (used by GitPages).
  • Wiki: developer-facing content, safe for public ¹
  • Pages: user-facing content, safe for public ¹
• Determine common theme/style to use across TACC WMA Repository docs.
  • Wiki:
    • this proposal ¹
    • the footer from this wiki (pattern was used to add footer to Core-Portal)
• Generate documentation as required.
  • Yes, please.

¹ ⚠︎ This does not match the intent of moving code-dependent docs closer to code.

[taoteg]

What is the purpose of duplicating developer-oriented documentation that would live in gitpages (and thus be in the codebase repo locally) in a wiki?

I thought the intention was to move the docs closer to the actual code, not create another resource to maintain separate from the codebae (and withuot any meaningful enforcement capabilities beyond manually reviewing, unlike gitpage content where changes to development workflows or procedures can be reviewed as part of the PR that changes them).

If we are going the wiki route (which I honestly do not like for developer documentation) then I see no point in the gitpages.

#ChangeMyMind

[taoteg]

Note that anything in the repo should be "public facing safe" because these are no longer private repos. Anyone can pull this code and read it or its documentation.

[wesleyboar]

I do not intend to suggest "duplicating developer-oriented documentation".

My distinction is not compatible with "move the docs closer to the actual code". I had forgotten that intention.

Yes, on "public facing safe". I clarified only because was thinking of Confluence as I wrote, which is private.

I decline my proposal, as is. I will revisit and update it. Wiki should not have "code-dependent" docs.

You may notice code-dependent documents in the Wiki's for Core-CMS, cms-site-resources, and Core-Portal. I will move these to GitHub Pages.