Phil's initial ideas for discussion! #1
Replies: 1 comment 1 reply
-
|
Hi @phildexter. Just to confirm, by taxonomies, you're referring to tagging, correct? The only general reason I can think of to include tagging would be to improve search results. I'm not familiar enough with our preferred search tools to know if tags would be helpful or not. I think the vast majority of our content can be managed and organized through page types and child pages instead. The vast majority of the content will be documentation and that page format should be pretty standard across the board. If we ever start hosting tutorials down the line, those could have enough variation in them that tagging would be good to have but I feel like that's something we can decide on later on. Everything else here looks pretty good to me. |
Beta Was this translation helpful? Give feedback.
-
|
Great thanks Meagen. Yes taxonomies basically mean tagging, but not free tagging - controlled categories. I think I agree with your assessment generally! |
Beta Was this translation helpful? Give feedback.
-
Where will the site live and how will people find it?
EDITED: Having discussed this with the team, we think the site should be linked to from wagtail.org. It would be nice for us to have a bit of a hub that can act as a place Wagtail site builders can point new editors to as a one stop shop for them (a bit like this).
In terms of the DNS we think the best thing would be for us to go with guide.wagtail.org, rather than a subfolder like wagtail.org/guide. There are several reasons to do this:
The only drawbacks were around SEO - a subdomain is treated as a separate site entirely by Google so is worse in terms of search authority around "wagtail" generally. We feel like this drawback is somewhat limit though, as Wagtail itself is such a clear and obvious word for people looking for support to use in their search terms, so we feel confident about our ability to rank.
Content organisation
We will use the documentation system in 4 writing modes (Tutorial, How-to, Explanation, and Reference). The existing editor guide content doesn't match the intended writing modes and structure. We'll ask content specialists and the community to help. You do have to provide true-to-life content to showcase various pages and elements (headings, paragraphs, lists, images, etc).
Styling + Models
I think our designs should match the new swanky wagtail.org designs, pretty much. I don’t think this will add much effort to the overall build and content types and layouts should be fairly straight forwards.
I think we should be looking at two page types:
Homepage, that explains how the documentation is structured and give jump off points
Documentation Page that is used for all of the rest of the pages.
The Documentation page should list out any children it has at the top, and have page contents. Then it should contain the following content types:
I think it would be good to also have the forwards / back options as we have now, as well as breadcrumbs.
Do we need taxonomies? If so, why?
Search
We should have search!
Versioning and Translations
Every time a new Wagtail release is published, changes to the CMS need to be described in the editor guide. But projects will still be on an old Wagtail version. Users need to understand what Wagtail version they are on, and what version of the guide is relevant to them.
We need a default (latest) version that should load, with a switcher so you can go back to older version (like the developer docs).
We only want to serve guide versions of supported Wagtail versions. https://github.com/wagtail/wagtail/wiki/Release-schedule
We will use language code as our versioning. E.g.
WAGTAIL_CONTENT_LANGUAGES = [
"en-2.16",
"en-3.0",
"en-latest",
"fr-2.16",
"fr-3.0",
"fr-latest",
"nl-2.16",
"nl-3.0",
"nl-3.0",
]
That would give these i18n URL prefixes:
/en-2-16/
/en-3-0/
/en-latest/
/fr-2-16/
/fr-3-0/
/fr-latest/
/nl-2-16/
/nl-3-0/
/nl-latest/
Workflow for a new Wagtail release (to be confirmed):
In terms of translations, I would suggest that we start off just using simple translations for this project. I think a stretch goal would be to install wagtail-localise.
Feedback and contributions
We want to quickly understand which parts of the documentation are working well and which are not. Ideally we’d like a way for users to let us know more specifically what they do / don’t like.
We want this to be super simple and fast. No login.
And we want this to go somewhere clear and obvious so we get notifications, and ideally a central item that can be triaged for action / ignoring.
We need to also avoid robots.
Options:
Hosting
EDITED: We will host this as a standalone wagtail instance. An alternative that was considered was to host this as a multi-site with wagtail.org. However, we felt like a separate site would be most appropriate from a risk, complexity and dependencies perspective.
Documentation and Unit tests
You have to write documentation on how to set up the website.
We expect tests and sufficient coverage.
Tooling
We'll need to decide on which tooling to use for our frontend / backend build. @allcaps to own this.
Extended goals
Beta Was this translation helpful? Give feedback.
All reactions