GSoC 2022: Editor's Guide - Separate Website

[lb-]

Is your proposal related to a problem?

Separating The Editor's Guide so that it is easier to extend per project and potentially integrate in the CMS itself

• When providing Wagtail to clients, it would be great to have a simpler way to integrate the user facing documentation (aka editor's guide) with Wagtail itself.

• Sending users to the technical documentation, even though there is a sub-set focused on editors can be confusing and potentially overwhelming.

• Often times there are subtle differences between an implementation of Wagtail and that presented in the editor's guide.

• It would be really nice to be able to add a 'help' section to the admin menu that itself would render the editor's guide within the CMS.

• Note: Not sure if this should become a RFC but wanted to start the discussion here.

Describe the solution you'd like

Options / Ideas

• Convert the editor's guide to markdown (this is just simply more convenient) and emulate the method of the Wagtail Styleguide allowing it to be added as an app and then brought in to the CMS admin interface as a menu item. Files can be 'overridden' by simply replacing them via the static folder or templates initially.
• Move the editor's guide to a separate repo completely, host it on its own (eg. editors.wagtail.io ) and use a different docs interface that is easy to replicate/host simply.
• Documentation on how to 'output' the user guide and then modify parts and serve it on its own simply.
• Separate repo might work against us with updates happening out of sync with releases and it not being as visible in terms of PRs and Issues.

Additional context

• https://foundation.mozilla.org/en/docs/how-do-i-wagtail/ - great clean user facing docs

[kaedroho]

+1

I agree with all your points, but would add another: This is the one part of the documentation that really should be translated.

As for options, I would be in favour of moving this to a separate repo/site as Wagtail's editor experience changes so slowly that it wouldn't need to version it for every release.

[thibaudcolas]

I’ve moved this to GitHub Discussions as it feels like this is rather open-ended and we could use further… discussion. cc @lb- @jacobtoppm @allcaps

@phildexter could you share more details about your plan to move the editor’s guide to be managed in a CMS? (either wagtail.io or separate)

Here are the pros and cons / considerations raised when discussing this internally on Slack:

We loose versioning (but I don't think that is a big deal). We win a lot of freedom to design these pages to target the specific audience. Editors and managers that should not have to browse technical docs to find a user guide.

Could help with having: “a custom version that is hosted within your own wagtail instance.”

https://github.com/kevinhowbrook/wagtailguide as a public example of using Wagtail to manage an editor guide

Personally I think the versioning is useful, and I know we've updated it for more than bulk actions - personally I've done it for workflow and commenting for example

I would be concerned about trading "hard to edit for non devs" for "impossible to edit without privileged CMS access"... (edited)

I think we should have this as code first and CMS editable second, surely we could just use markdown, then make a wagtail interface that allows editing of this content and spits out a changed markdown file (for github upload?).

Here are current contributor stats for reference:

According to the commits on docs/ there have only been 41 different committers to the editor manual over 100 commits. From those 41 contributors, 15 are or have been in the core team, and another 16 are regular contributors. So over the history of the project it’s only 10 people / 11 commits that might have been hindered by the editor manual not being editable in git.
This is in contrast with 434 contributors, 3629 commits for the whole of the documentation

[phildexter]

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.

[lb-]

Update - this, in some form, has been put down as a GSOC project idea.
https://github.com/wagtail/wagtail/wiki/Google-Summer-of-Code-2022#make-wagtail-editor-guide-a-stand-alone-project

[lb-]

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

[allcaps]

Just wanted to let you know I'm working on Wagtail Guide. https://github.com/allcaps/wagtail-guide a package to create Wagtail user guides.

[allcaps]

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.

[phildexter]

Hi all.

I'd again like to make the case for the editor docs become a Wagtail site. Having spoken briefly to @kaedroho about this, I know he also favours this approach.

There are a few key reasons:

• Dogfooding. I believe Wagtail is a great content management system, and would recommend it to teams who need to manage sites like this. By managing our documentation in this way, we’ll put our money where our mouth is, and get some real user experience ourselves.
• Lower the barrier to entry. I think if we host our docs in Wagtail, we can make it easier for less technical people to make updates than it would be if hosted in Github. I believe we have so few updates by so few people on the existing editor guide because those that would like to update it are unable to.

How it could work in practice:

• We could set up an editor guide sub-team, who are all admins of the editors guide site and own its content and structure.
• We could allow the sub-team to control user access for others, so other community members can have certain permissions to allow them to edit, moderate or publish.
• We could make it simple for members of the community to submit updates or raise where they see errors, using something like Wagtail forms.

Potential drawbacks

• Versioning. We still need documentation of older versions of Wagtail available when new Wagtail versions are released so that editors using older versions still have guidance. In reality I think we could probably just keep documentation for supported LTS releases. One way of doing this would be to have a page structure that starts with the release number, before going into the documentation itself. E.g.

Root
2.7 LTS
Introduction
Getting started
The Wagtail demo site
…
2.11 LTS
Introduction
Getting started
The Wagtail demo site
…
2.15 LTS
Introduction
Getting started
The Wagtail demo site
…

When a new version of Wagtail is released we just keep updating the same pages, until an LTS release is made. At that point we take a copy of those pages and rename the top page to the new release name. The LTS release stays static, and we just work on the new release pages.

I know this is something that is being considered for a GSOC project, so I wanted to raise this now as it feels quite important to me - the editor docs to date haven't been great, and I think we could make them really good with something that looks a bit like this...

Happy to hear all thoughts, or jump on a call to discuss further with people that want to.

[lb-]

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.

[phildexter]

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.

[lb-]

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.

[vibhuti019]

@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.

[lb-]

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.

[allcaps]

I'm sure we can come up with and implement technical solutions, but maybe we should also start making a plan to structure the content?

The current user guide is not too good. It describes all kinds of details, is too complete. It is a wall of text. Sure, we are -more or less- obliged to describe all features. But by better structuring the content, it could be more accessible.

• A beginner who wants to acquire basic skills needs clear tutorials: "Click here, do this, do that ...". Without any digression on irrelevant details. Topics such as login, create page, add image and document.

• More experienced users will consult the User Guide to solve a specific problem. This user already has basic knowledge and skills. An explanation in a series of steps need only give the outline. A how-to guide with a concise step-by-step plan. Examples: automatic publishing, creating redirects, search promotion.

• Perhaps a reference list or glossary would be helpful too? (not sure). An overview of page elements and their names. If people know the names of elements, they can also communicate better about them. Example: page header, breadcrumb, action menu, user menu, inline panel, struct block, etc. I'm not sure if this section is really necessary. But I have had requests from developers who would appreciate a name/image reference of Wagtail UI elements. I assume this is helpful for content editors too.

• Experts who want to know exactly how a feature works would benefit more from a background information/explanation section. Such a page will not have a tutorial or step-by-step guide. But for example explaining what actions happen when you use comments. Who gets a mail, and when, etc, how this relates to permissions, and why.

Each section has its own target audience, purpose and writing mode. Its unique style that brings focus. Sections should crosslink. For example background information can point to the relevant how-to guide and back.

This pattern is often found in documentation. I think it could -in some form- also apply to the user guide.

Proposed sections are:

• Tutorial (basic learning)
• How-to guides (goal solving)
• Reference (plain information)
• Explanation (deep understanding)

This 'documentation structuring strategy' is inspired by (and better explained at) https://documentation.divio.com/

[lb-]

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

[Hitansh-Shah]

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.😇

[Scotchester]

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

[0saurabh0]

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.

[Scotchester]

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.

[thibaudcolas]

Notes from today’s meeting based on questions by Anuja, Saurabh, Juan:

• Technologies we will explore with this project: ?? I wasn’t paying attention :) Coen suggests suggesting options :)
• How much Django is required: quite a bit (since Wagtail is built on Django), but we have a lot of people skilled with Django and Wagtail to help
• Content is in reStructuredTest & Markdown, will move over to Wagtail

[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? If yes then can we integrate sphinx-wagtail-theme with wagtail templates?

[0saurabh0]

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

[Hitansh-Shah]

Thanks @0saurabh0 for the info 🙌

[thibaudcolas]

@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.

[Hitansh-Shah]

@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.

[vibhuti019]

@lb- I have a question if we will allow a user to update certain pages in the guide via the feedback form, and once the changed guide is published, the admin of the project will have to make the changes in the GitHub repo too. Or the documentation will only be created on the server.
The github repo will not get updated even if I use file write or database

Can we use gitpython to update the github repository whenever a changed page is published?

[lb-]

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

[lb-]

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]

I have created figma designs of 2 pages one being the homepage and other being how each section will get visible.
Any suggestions or feedback would be awesome.
I tried to include most of the things suggested in this discussion.

Figma Link To Pages

[allcaps]

@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.

[vibhuti019]

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

[phildexter]

Thanks for these, some nice thoughts here.

[vibhuti019]

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

[0saurabh0]

A basic confusion.
only wagtail editor's guide is the one that needs modification not the other documentations ??

[PaarthAgarwal]

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.

[phildexter]

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.

[lb-]

California College of the Arts - Wagtail user guide
https://portal.cca.edu/help/wagtail-documentation/

Great user facing reference

[lb-]

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.

[cnk]

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

[lb-]

This is great! thanks @cnk

[Hitansh-Shah]

So I have doubt. It is written that we have to prepare a package using wagtail cookiecutter package, so does that mean that we have to prepare a separate template on top of wagtail cookiecutter package or we have to use wagtail cookiecutter package to create a basic app and then extend it.

[lb-]

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.

[Hitansh-Shah]

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.

[talkshrey]

Hi. Have we decided upon some technology we are going to use for developing the documentation?

[0saurabh0]

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

[lb-]

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

[allcaps]

Which features have the most priority in Editor's Guide?

The wiki gives some insight. But, I like to dive a little deeper. Note, this is not discussed with the other mentors. This is my view. Feedback and comments are welcome!

Let's look at what the end-user needs and derive from that the project requirements.

Users

The target audience are the content editors, moderators and administrators. They need a guide on how to work in the Wagtail admin interface. For them the following is important:

1. Correct and complete information.
2. Navigate information (pages, sections, navigation, hierarchy, table of contents, search, etc).
3. Linkable information (to share specific page sections)

I would like a documentation system with sections that have their own target audience, purpose and writing mode. Structuring and rewriting the existing content seems out of scope for GSoC. Providing tools to manage this work might be part of GSoC. For example internal page classification and workflows.

GSoC

Using the MoSCoW method.

Must have

• Wagtail Site
• UX/Graphic design
• Code under version control
• Automated test
• CI/CD
• Domain + hosting
• Frontend tooling
• Page types (Homepage, SERP, landing pages, tutorial page, how-to page, reference page, explanation page)
• Images
• Animated GIF
• Documents
• Workflows
• Internal content classification
• Header / footer / main nav / breadcrumbs
• Table of contents
• Responsive (desktop/tablet/mobile viewports)
• Favicon
• Robots.txt
• Sitemaps XML
• Correct meta tags
• Data migration of existing content into Wagtail site. Respect the new sections / types / layout.
• Development documentation

Should have

• Translation and localisation
• Versions
• Feedback mechanism

Could have

• A way to keep screenshots up to date

Won't have (this time)

The following points are mentioned on the wiki. But I can't see how this would work with content managed in a Wagtail site.

• Allow for the project to be imported into existing Wagtail projects and document how it can be built, customised and run (automatic screenshots) against those custom Wagtail installations
• Allow for additional pages/header/footer/feedback to be integrated
• Automatic screen recordings

[phildexter]

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...

[0saurabh0]

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)

[talkshrey]

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.

[0saurabh0]

Is it fully determined that the content of wagtail editor guide will be restrustured ??
And if not what are the major changes expected ??
will edit the proposal acccordingly.

[thibaudcolas]

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.

[allcaps]

Shared via Slack, but I'll post here to have the overview:

Dex and I read your proposals and are happy that you'd like to work on the Editor's Guide!

Most important feedback to all: The bulk of the work is creating the Wagtail website. We like to use features supplied by Wagtail to our benefit. Most proposals would be improved if they expand on the work involved to produce a Wagtail website.

We realised the desired implementation on our wiki is a bit sparse, therefore we'd like to give you these points:

Content

• 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. Rewriting the content is not part of GSoC. - 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)
• Data migration is a minor thing. Copy-pasting will get it done.
• Writing a data migration is allowed, but the amount of content is so small, that we estimate that it is hardly worth the effort.

User interface / frontend

• We aim for a 'look 'n feel' somewhere between the design of docs.wagtail.org and wagtail.org.
• Maybe borrow MKdocs material design theme? TBD
• Maybe an existing Twitter Boostrap theme? TBD
• We hope that by using an existing theme or a component framework we can ease development and make it easier to contribute/maintain.
• After we created a working site, we will invite a designer to give us tips on how to improve the website.

Versions

• 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 only want to serve guide versions of supported Wagtail versions.
  https://github.com/wagtail/wagtail/wiki/Release-schedule

Ways to provide versions of the guide are:

• Copy the whole page tree (and all related content)
• Baking a static site

Maybe we need to avoid the problem and maintain a single guide without versioning. We can label sections showing the relevant Wagtail versions?

All solutions have drawbacks and strengths. The exact implementation is to be decided. We like to hear your preference and motivation.

Translations

• Content will be translated in Wagtail https://docs.wagtail.org/en/stable/advanced_topics/i18n.html
• We need Simple Translation OR Wagtail Localize https://docs.wagtail.org/en/latest/reference/contrib/simple_translation.html or https://www.wagtail-localize.org/
• We need to translate and localize strings in code. https://docs.djangoproject.com/en/4.0/topics/i18n/translation/
• Transifex might be useful to crowd-source UI translation.

Feedback and contributions

• People might provide feedback.
• MKdocs has a cool plugin
  https://squidfunk.github.io/mkdocs-material/setup/adding-a-comment-system/#giscus-integration
• We want the feedback form to post to the Wagtail admin
• Maybe mail or Slack feedback.
• It would be nice to link feedback to a piece of text instead of the whole page. (extended goal)
• We do not want a forum. That would require too much maintenance and management.

We want to give more involved people a way to contribute. Working title is 'Wagtail as a Wiki'.

• Login and account creation via social auth.
• Automatically assign minimal permissions. A user can create a draft and submit it for moderator approval.
• People who regularly contribute and seem trustworthy can be invited to become moderators.

Hosting

• A separate site.
• Subdomain or folder? Eg: guide.wagtail.org or wagtail.org/guide TBD

Content reports (extended goal)

Present reports in an overview and/or per page:

• View statistics
• Comment statistics
• Ageing pages (is an existing feature)
• Statistics in some overview
• Statistics on the edit view of a page

Development

• Code in Git and on Github.
• We will set up CI/CD to test and deploy regularly.
• We will manage progress in a Github issue tracker.
• You have to write documentation on how to set up the website.
• We expect tests and sufficient coverage.

What do you need from us?

• List things that are out of your control, that you need from us.

Screenshots (extended goal)

We look for a way to make screenshots and update images on the Wagtail site. Note that screenshots need to match the content languages.
This is an extended goal. But we like to hear your approach/proposal.

Some ideas (extended goals)

• Internal classification of content. Tagging, examples: 'needs-work', 'rewrite-as-tutorial', 'outdated', etc
• External use of tags to group pages: 'workflow', 'users', 'page-edit', 'permissions'
• SEO and social
• Add YOAST
• Add og:image
• Add twitter card
• RSS Feeds
• sitemaps.xml

[0saurabh0]

Development

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

Just for clarification
which site is being referred here?

[PaarthAgarwal]

The "Editor's guide" website

[allcaps]

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.

[thibaudcolas]

For people following along, we now have the site repository at https://github.com/wagtail/guide, a preview of current progress at https://wagtail.org/editor-guide-site, and a blog post from @Hitansh-Shah and team on where we got to: Google Summer of Code: Wagtail Editor Guide