Skip to content

Docs: Diátaxis refactor - iteration 4 high-level tracking #9749

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
10 tasks
benjaoming opened this issue Nov 21, 2022 · 0 comments
Open
10 tasks

Docs: Diátaxis refactor - iteration 4 high-level tracking #9749

benjaoming opened this issue Nov 21, 2022 · 0 comments
Labels
Improvement Minor improvement to code Needed: documentation Documentation is required

Comments

@benjaoming
Copy link
Contributor

benjaoming commented Nov 21, 2022

Successor of #9748

This is a high-level issue moved from the initial planning document. Further issues may be opened and linked from here.

  • Acceptance criteria: Documentation no longer has anything that makes it possible to tell that it’s undergoing a restructure.

  • Outcome: Brushing off all the rough corners, adding new index pages for Explanation and How-to content, new “All Features” index page (potentially adding features via data templates), small tweaks to the main index page to match the new structure.

New

  • We might want a page like "Setting up a local authoring environment and investigating errors" to exist in Tutorials. There is some tension around the length of the sidebar, so might investigate adding a major sub-level "Getting started" or "Creating your first project" vs. "Adding an existing project" etc.
  • Develop Explanation / Collaboration / Teams and Team management
  • Develop Explanation / Traffic Analytics and move the current file (which is a how-to). We might be able to develop a better explanation of Traffic Analytics, perhaps combining it with our current SEO guide.
  • Develop How-to Guides / Security and Access / How to create and manage a team
  • Suggestion to add "Working with themes and branding" in Explanation / Writing Documentation
  • "Custom 404s" added in Explanation / Publishing: How documentation is shared with the world
  • Develop a new "All features" index in Reference
  • Localization was further developed in Docs: Relabel Localization as Explanation (Diátaxis) #9790 - do we want to expand it?
  • Main index page sub-section refinements
    • Explanation
    • How-to Guides
    • Reference
    • Features removed or replaced (TBD)

Remove

  • Any existing empty levels or old articles are removed or modified to an acceptable quality and Diátaxis alignment. This should not be the case.
@benjaoming benjaoming added Improvement Minor improvement to code Needed: documentation Documentation is required labels Nov 21, 2022
@benjaoming benjaoming self-assigned this Nov 21, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Improvement Minor improvement to code Needed: documentation Documentation is required
Projects
None yet
Development

No branches or pull requests

1 participant