Thanks @thibaudcolas

When you say we'd lose versioning, I guess you're meaning having an editor guide version that is clearly tied to a Wagtail release? Obviously Wagtail has versioning of page, but not quite of sites, I suppose. I guess one way around this would be to create a new instance of the site for each new quarterly release, leaving the old one available for those that need it?

The "hard to edit for non devs" for "impossible to edit without privileged CMS access" is an interesting point. I suppose right now there is a way to submit updates for anyone who understands what it is. But it's not straightforwards to write down, or to follow for non-devs. Though it would be impossible for someone who didn't have CMS access to submit an update to a Wagtail page, it feels like it's a surmountable challenge - my initial thought it we have a form on each page that asks the person what their update is, or asks if they want to get access to make more than one update into the future. We then give them access, and set up the relevant workflows so they can't publish.

I'd be nervous about us spinning a custom solution, purely because it's another system to maintain, another custom thing for someone to fix if it goes wrong. Having said that, I don't think I fully understand everything you're suggesting here.

The contributors statistics are interesting. One way to read it is, no one is really making updates anyway so we're not losing much here. The other way is, all the people who might care to update it can't, and therefore they never make it into the statistics. I'd like to think that if we had a form on the editors guide where people could submit updates etc, we'd get a better quality end result.

Created this as a bit of a precursor work to making the editor's guide something we can pull out a bit easier plus also helps the core code if that does not happen for some time. #8106

Just to clarify a bit, allcaps/wagtail-guide is my pet project. It can be a solution, but doesn't have to be the solution for Wagtail.

This discussion is to get a clearer view of what we find important and discover possibilities. All ideas and suggestions are welcome.

sorry to spam but we may not need to keep an 'output' of content in any repo but instead just provide this content via its own API - other usages of the app will just pull in the latest page content via the guide.wagtail.org/api

we can version things by tagging (somehow) a point in time and the api (and and the site itself) can return a version of its own pages at that point in time.

Images become harder this way, but solvable.

Thanks for the feedback!

@lb- I like your idea. As far I can see you're generally on board with Wagtail for content, with some specifics of how we should set it up for versioning.

I guess there is a 2 step approach here, where we firstly create guide.wagtail.org and develop the wagtail-guide/django app. That way we could start getting the editor docs quality up, and have something live to develop the django app against / prove that it works.

I agree, and we may find that we end up in a simpler place where the site repo also contains the code for a reusable app in other projects.

Obviously, the 'use the guide in your own admin' is a future goal.

The primary goals, maybe that is where we should start, are probably something along the lines of;

• Discoverability - Not buried in the technical docs, it can even become a bit of a promo piece for those interested in adopting Wagtail.
• Audience focus - Easier feedback and improvements from non-technical users.
• Relevance - Content that is relevant to the version a user is on (remembering we will still have older versions of the docs to fallback/link to, but it would be nice to at minimum serve 2.15 LTS and newer on the new site), and relevant to the features they are using.
• Reusability - Third, making the content remixable/reusable in other locations, along with adapting it to other's specific Wagtail installations.

Exciting, and I really am keen to hear other's thoughts on this also.

@lb- As I have seen in the current documentation the markdown files have been created in .txt files. I don't think it will a issue to show the old documentation.

Please specify the reusability and feedback part, I think it's similar to components like we have js frameworks and for feedbacks, can we implement forums.

hey @vibhuti019 thanks for your interest.

I agree that bringing in the historic versions of the either built (html) or raw (rst/MD) editor's guide should not be too tricky. We would need to work out how to manage their serving and building in the new site though as we would likely not want to rely on Sphinx.

Feedback - we want a way for anyone to submit a feedback form on the guide pages. My recommendation is we use the Wagtail form builder for this (in the goal of dogfooding). This data would sit in the Wagtail instance and need to be managed/actioned somehow. The difference is that this feedback would not, necessarily, be on GitHub in a public way.

Reusability - I have loved the idea of the wagtial guide being in the Wagtail admin itself. Imagine a link in the menu 'guide' and then you are taken to the editor's guide content but you are still within Wagtail. Now take that a step further and imagine the screenshots match what you actually are seeing (you may have different colours or logos in your admin). Even further you can switch on/off parts of the guide based on what features you are using. Finally, bits of the content could be editable by users within that Wagtail instance. This is a stretch and it's good to start small to see where the need is but this is what I mean by reusability.

As an aside - that documentation system guide is so good - I know we started towards adopting it in the main Wagtail docs but I wonder how we can move in more of that direction (anyone know of an existing discussion that covers this?).

Update: found it #6781

Hello everyone, I am Hitansh. I recently joined wagtail community and I am excited to contribute and learn from it. I read this amazing project planning/structure @allcaps prepared. It is precise and I found it very interesting. If I am not wrong this project is there in Gsoc'22 ideas list. Well, I would love to do this project for Gsoc. I have already followed the pinned resources in wagtail slack for getting acquainted with wagtail. So can anyone tell me about the next steps for this project like whether I should start with the proposal or I should look into some other stuffs to get better idea about this project. Thanks for the help. I look forward to build something with and for the community.😇

This is the new permanent home for that documentation framework: https://diataxis.fr/

This is the new permanent home for that documentation framework: https://diataxis.fr/

I think It's more or less same as @allcaps suggested above.

This is the new permanent home for that documentation framework: https://diataxis.fr/

I think It's more or less same as @allcaps suggested above.

It is more-or-less the same, yes, but the one I linked to will get future updates by the original author, whereas the one linked to by @allcaps will not.

hi @Hitansh-Shah

So I have a question. are we going to use sphinx for the new doc website for editor's guide or instead we will use wagtail itself so that whatever pages we define for different part of the editor's docs, we can try to reuse them in the admin's page too. Also if we use wagtail then are we going to keep the theme of the documentation same?

As far as i know, from the meetings and mentors, it's not fully determined that, the guide is to be new wagtail site. or perhaps it will be hosted as part of wagtail.org site, in a multi site manner.
As told earlier you can propose your POV

Thanks @0saurabh0 for the info 🙌

@Hitansh-Shah based on this message a few days ago: #7824 (comment)

I think it’s 99% sure we’ll be using Wagtail itself to build this site. @0saurabh0 is right that we don’t know exactly whether it’s on wagtail.org or elsewhere. I don’t think the theme has been discussed. Personally I don’t see that much value in reusing the existing sphinx-wagtail-theme.

@thibaudcolas Got it 👍️. I guess then I will try to plan a outline of what and how we can do things, the structure of the doc. And then once we have decided that, we can start working on the content and the theme. I will share if I come up with anything.

Hey. Others may add their thoughts but here is how I think this could work.

• We create a single EmailFormPage that will be accessible on every page via a modal from a button
• this form will have a hidden field which will capture the relevant page is
• the feedback form will ask all the usual feedback items and then be linked via the hidden field to the page it was submitted on
• enhancement - the form submissions emails the submitter a copy of their feedback
• enhancement - each submission also gets a uuid and the feedback can be made public in a different part of the Wagtail site for additional comments or +1
• we could also consider the form submissions triggers a workflow within the CMS to be easier to track actions against it.
• at some point we would need to flag that the feedback has been processed

As for providing the content in a non-db format, that is up for discussion and proposed ideas.

I envisage we would have the repo store a 'historic' build based on each wagtail version maybe.

@vibhuti019 Thank you. Great! Notice that the content is managed in Wagtail CMS. The Github button is not relevant to the audience.

This gives a nice impression.

@allcaps I have removed it. I thought we can give a link to the editor's guide repository via that button.

Thanks for these, some nice thoughts here.

I have updated with forum page.
It will be visible only to the contributors.
Each new feedback will create a question on forum.

Our documentation in its current form may appear overwhelming for non technical users. I believe that's why we are moving Editor's Guide part specifically.

Yes that's right. Developer documentation will stay where and as it is. We will move the editors guide out to be managed through a Wagtail site. We'll need to link between the two I suspect at points, but generally the audience for these are different enough that they can standalone.

Reaching out to some others in the core team for any links they can share for the content they use when build new sites and training new editors.

@cnk @KalobTaulien @FlipperPA @nmorduch @chosak

Sorry for the mention spam, just ignore if there is nothing you can add or share publicly, I know some organisations have content for editors but it is not publicly visible.

Caltech has publicly available editor documentation - but it is pretty focused on the blocks we have built to support our current site theme / branding. https://sites.caltech.edu When people get a new site, we refer them to that site and to specific sections of the Wagtail docs.

We get feedback that we need a "getting started" or tutorial for new sites - probably best handled as a screencast. So far I haven't been willing to do one but might try the technique Coen showed off at this year's WagtailSpace: https://www.youtube.com/watch?v=E3-kFY6jPPY

This is great! thanks @cnk

There are two parts to this whole project, the first is bringing the existing content (with some likely reworking) to a standalone Wagtail site.

The second is to provide a way to embed this content into a Wagtail site itself (in the admin section) and maybe allow for modifications as needed.

Ok gotcha. So it basically meant that cookiecutter can be used to bootstrap into the editor's standalone project and then convert the existing md/rst/images files into django views and urls.

I think it's pretty clear that we'll be using wagtail itself for building the site.
source - #7824 (reply in thread)

Yep. That's correct - the content will be a Wagtail site.

I like these ideas and agree with the scope generally!

I think one thing I'd like to consider would be the scope of writing the new content, and if that is in scope of this project or not. I'd have thought that part of that would be in scope for this project.

I think we should also think about what we would mean by translation localisation - would we want to use the same translation system that we use Wagtail core translations, and hook Wagtail up to that? I guess initially we could just have it managed in Wagtail itself...

At the current stage, I think restructuring of content is more important than the rewriting the content. as @allcaps suggested above..
one way of doing this can be, first we can organise and structure the base and then start adding the content with modification (where
required) or rewrite the content (where necessary).
Then we can start adding features one by one like the 'feedback form'.
It'll take time and more efforts but can be doable ??
otherwise this approach sounds good too #7824 (comment)

At the current stage, I think restructuring of content is more important than the rewriting the content. as @allcaps suggested above.. one way of doing this can be, first we can organise and structure the base and then start adding the content with modification (where required) or rewrite the content (where necessary). Then we can start adding features one by one like the 'feedback form'. It'll take time and more efforts but can be doable ?? otherwise this approach sounds good too #7824 (comment)

I agree with Phil's point, we may need to prioritise restructuring of the content. I had a suggestion of adding references to the editor guide (like a reference sheet or tree of some sort) so that it is easier to refer to the documentation.

This has already been answered by @allcaps here. Note the content itself / its structure isn’t something the GSoC contributor will have to handle – as far as the GSoC project goes, implementing the site with the existing content migrated would be a good outcome.

Development

• You have to write documentation on how to set up the website.

Just for clarification
which site is being referred here?

The "Editor's guide" website

Please, explain the comments statistics, does it include feedbacks, or it will more like internal commenting?

If we receive feedback on various parts of the guide, that feedback needs to be visible in the admin interface. We probably store feedback in a model, and have a foreign key pointing to the related page. With this we can make an overview and give some statistics:

An overview might be an admin list view. The list will show:

• Title + link to the edit view
• Page view count
• :) count
• :( count
• Feedback text count
• Time since last page edit

With this data in an overview, it becomes clear which pages perform well, and which need attention.
We probably want this overview page AND totals on the edit page.

The feedback and contribution part is a bit unclear to me. Can you please brief what is need in that part?

We envision various levels of involvement from our visitors and contributors.

Simple feedback

Examples:

• Jane is a content editor, doesn't know what a workflow is, reads the guide workflow page, she understands now. She hits :)
• John is a content editor, doesn't know what a workflow is, reads the guide workflow page, he does NOT understand and hits :(
• John is presented with a text area and submit button to give feedback on what he does not understand and how we might improve.

This is similar to the MKDocs 'Is this page helpful' example: https://squidfunk.github.io/mkdocs-material/setup/adding-a-comment-system/#giscus-integration.

These feedback :), :(, and texts are linked to a page.

Nice to have: feedback linked to a specific section or paragraph on the page, instead of linking to the whole page. This gives us more context on what the feedback is about.

Contributing

Some people are more motivated, and like to contribute/improve the guide. They should be able to rewrite pages or submit new pages.

This is the replacement for the current situation. Currently, the guide lives in the Wagtail documentation code (rst/md). We use Git and pull request to make changes. By making contributing easier (edits via the Wagtail admin), we hope non-technical people will contribute to the guide too.

It goes something like this:

• The user creates an account via social auth
• On account creation, they automatically get basic access to the Wagtail admin
• They have permissions to edit and create pages.
• They can 'submit for moderators approval' (not publish directly).
• A moderator will review and publish, or reject and request changes.

This is the default Wagtail workflow.

Moderators

• Trusted users can be made moderators. They get permissions to review a contribution and publish it.

tldr; Feedback :), :( (and optionally some text) is submitted by visitor. They fire and forget. Contributors suggest changes, they use the default Wagtail workflow and receive status updates (reject, change requested, or publish). Contributors can be promoted to moderators.