Chloe Bringmann 2:50 pm on April 27, 2020
Tags: season of docs ( 6 )

Season of Docs: A Call For Projects!

Thank you to all who responded to @kenshino initial call for mentors as we prepare to participate in this year’s Season of Docs. As this season’s primary administrator, I am looking forward to working with you all!

Mentors

For those listed below, please be sure to familiarize yourself with the responsibilities of being a mentor and apply before the deadline of May 4th 20:00 UTC. If you have any questions, @kenshino will be acting as a support throughout the mentoring process.

Milana Cap, @milana_cap
Estela Rueda, @estelaris
Ahmad Awais, @mrahmadawais
Usman Kahlid, @usmankhalid
John Zenith, @zenithcity
Tim O’Haver, @timohaver
Alain Schlesser, @schlessera
Marcio Zebedeu, @marcio-zebedeu
Felipe Elia, @felipeelia
M Asif Rahman, @asif2bd
MakeWebBetter, @makewebbetter
Shubham Nigam, @iamshubhamnigam

Next Step: Project Ideas List

Our next step is to create a project ideas list. This list should include documentation projects that would benefit from the work of a technical writer. Each of these projects will need the guidance of two mentors. Please add your project ideas as a comment below by Thursday, April 30th UTC 11:59.

#season-of-docs

Jon (Kenshino) 3:40 pm on April 27, 2020
Please note that all mentors are required to post at least one idea.

Because we need 2 mentors per project, we can only have 6 projects. So we’ll choose 6 ideas from a total of ~12. (I might throw some in!)

For each project idea, please provide the following details

Project name: Choose a concise but descriptive title.
Description: A longer description of the documentation work required. Describe your initial idea in detail. Offer opportunities for any interested technical writers to expand or refine the idea.
Related material:
- Link to the open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. project that needs documentation.
- If you’re proposing a technical writing project that involves updates to an existing documentation set, link to that documentation set.
- If you’re proposing a tutorial or a set of how-to guides, describe the features or use cases that need documenting.
- If you’re proposing a contributor’s guide, link to any existing README file or other relevant material if present. If there’s nothing available yet, it’s fine to say that.
- Include links to similar documentation in other projects, if relevant.
Please do so by 30th April UTC 11:59
- MakeWebBetter 2:57 pm on April 29, 2020
  Project Name: Most Popular Security Attacks
  
  Description:
  The idea of this project is according to need of WordPress Users, there are plenty of security breaches issues we heard of. So we can plan to create a documentation where we collect some most popular and not more complex issues and we mention fixation also of that kind of issue so that users can learn and solve their issues.
  
  Related material:
  - Link to the open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. project that needs documentation – https://wordpress.org/support/article
  - Update an existing documentation – https://wordpress.org/support/article/brute-force-attacks/
  - We can have a documentation in section wise actually we can include 2-3 attacks issue and can explain what effect on your website, how to prevent and fastest way to fix and protect your website.
Milana Cap 9:09 am on April 28, 2020
Project Name: Extending BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Editor

Description:
Documentation on developing on top of Block Editor is, depending on the topic, either scarce, outdated or non existent. Considering that Block Editor is a significant language leap for WordPress developers, I think the project itself would benefit a lot from having detailed documentation in a form of guides or tutorials, on how to utilize and extend coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. functionality and what the best practices are.

Related material:
- Link to the open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. project that needs documentation – https://developer.wordpress.org/block-editor/
- Updates to an existing documentation set – https://developer.wordpress.org/block-editor/tutorials/
- Features that need documenting: creating custom blocks (basic webpack setup, what plugins are used and why), using editor’s components in custom blocks, using core blocks in custom blocks, using data stores, using all the hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., block settings, pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party sidebars, RichText format types etc. Really, everything.
- Link to similar documentation in other projects – https://www.gatsbyjs.org/tutorial/
Estela Rueda 2:33 pm on April 29, 2020
Project Name: Improving article discoverability

Description:
During the design process, it was discovered that categories are not used to classify documentation articles and an article may have more than 2 categories instead of using tags to related articles. This makes it difficult for users to search, as they can click on a categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. > article, and hit the return button only to find themselves in an entirely different category. Another issue is the titles which in some cases do not properly describe what the article is about.

Related material:
- List of articles in WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org//documentation, including categories: https://wordpress.org/support/
- Work that has been done to recommend different categories/subcategories for articles https://docs.google.com/spreadsheets/d/1_Ea2yeF5Rfy_YDk7pBRJ4rdljhMjygXFqBq8gWwhbaE/edit?usp=sharing
- Findings in the reclassification of WordPress.org documentation https://make.wordpress.org/docs/2020/02/21/findings-in-the-reclassification-of-wordpress-org-documentation/
- Category term archive https://github.com/WordPress/HelpHub/issues/231
- No search results should guide the user to forums https://github.com/WordPress/HelpHub/issues/47
M Asif Rahman 7:47 pm on April 30, 2020
Project Name: Curate Existing HelpHub Article To Create Pillar Contents
Description:
We are continuously creating more contents in HelpHub, but when comes to basic questions like “Locally Host WordPress” or “How To Secure WordPress”, we have related content as separate CPT, but not one article to answer completely, that will link all existing content, and guide people instead of confusing them, but in current setup the more content we create it’s good for SEO, and similarly confusing for Humans!
Related material:
- Link to the open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. project that needs documentation: https://wordpress.org/support/
- I am proposing ‘Pillar Content” that will be curated collection of existing content that will direct guide users in finding more authenticated information. Like “How To Secure WordPress” will give precise guideline and will link and resources from following contents
* https://wordpress.org/support/article/hardening-wordpress/
* https://wordpress.org/support/article/changing-file-permissions/
* https://wordpress.org/support/article/why-should-i-use-https/
* https://wordpress.org/support/article/brute-force-attacks/
* https://wordpress.org/support/article/password-best-practices/
- Include links to similar documentation in other projects:
* https://developer.github.com/v4/guides/intro-to-graphql/
* https://devcenter.heroku.com/articles/getting-started-with-rails5
* https://www.gatsbyjs.org/tutorial/part-four/
johnzenith 2:14 am on May 1, 2020
Project Name: WordPress Development Configuration Guide

Description:
Code misconfiguration and setup can introduce security bridges and break security endpoints, thereby leaving the door open for walware Infections and cryptographic attacks.
Creating a configuration guide or overview for developing in WordPress will be very useful. Although, some of these already exists, but they’re not organized or put together in our place. For example, the configuration Guide will have several sections as: files and directories, debugging, nonces, database, WordPress salt, constants, queries, global vars, htaccess, password, httpsHTTPS HTTPS is an acronym for Hyper Text Transfer Protocol Secure. HTTPS is the secure version of HTTP, the protocol over which data is sent between your browser and the website that you are connected to. The 'S' at the end of HTTPS stands for 'Secure'. It means all communications between your browser and the website are encrypted. This is especially helpful for protecting sensitive data like banking information., etc.

Related Material
- Link to the open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. project that needs documentation: https://wordpress.org/support/article
- Updates to existing documentations: https://wordpress.org/support/article/hardening-wordpress, https://wordpress.org/support/article/changing-file-permissions,
  https://wordpress.org/support/article/debugging-in-wordpress, https://wordpress.org/support/category/security
- The configuration guide will be broken down into sections that will address specific issue or setup. For existing resources, they can be referenced accordingly. The main idea behind this configuration guide is to organize WordPress configuration settings into a single base.
Jon (Kenshino) 12:33 pm on May 1, 2020

Project name: Tracking Doc Suggestions / Updates
Description: So we don’t have a unified tracking system for when a doc needs updates. People could do it on MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. (which is really for code changes to WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/) or report them on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.. Sometimes I even see things on Twitter. It’s impossible for people to know if a doc is going through updates or is simply outdated. Some projects use TrelloTrello Project management system using the concepts of boards and cards to organize tasks in a sane way. This is what the make.wordpress.com/marketing team uses for example: https://trello.com/b/8UGHVBu8/wp-marketing. for short term purposes. Some projects use GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/.

We really ought to have a unified tracking system so that we can track these requests and the work to fulfill such requests.

And we need tocreate a process to utilise this system properly.

Related material:
None at the moment. It’s new!
- M Asif Rahman 12:57 pm on May 1, 2020
  
  Nice suggestion, it will help contributors a lot and will welcome more first time contributors.
Jon (Kenshino) 1:08 pm on May 1, 2020
Project name: A full and renewed set of documentation style guide
Description: We’ve written some style guides along the way but many of those applied to specific handbooks or projects we worked on.

But there isn’t a unified style guide nor is it actually complete.

We could look at coming up with new style guides while fixing up older ones or simply adopt a great existing one with compatible licenses.

Related material:
- Our current style guide: https://make.wordpress.org/docs/handbook/documentation-team-handbook/
- Google’s dev style guidehttps://developers.google.com/style
Jon (Kenshino) 1:19 pm on May 1, 2020
Project name: Make user documentation more helpful
Description: Our end user documentation is somewhat a bit of a mixed bag. It was written over the years by many people with different writing styles and viewpoints.

Some of it is written with the expectation that the user already understands WordPress or a CMS.

It is difficult for seasoned users of WordPress to write documentation for the unwary. We simply don’t understand where the problems are.

The end user documentation can use a fresh eye on the approach.

Related material:
- User Documentation hub code named HelpHub – https://wordpress.org/support/
- An example of well written user documentation – https://slack.com/intl/en-gb/help/categories/360000049043-Getting-started
Jon (Kenshino) 1:32 pm on May 1, 2020
Project name: Improve Existing Development Documentation and handbooks
Description: We’ve a lot of developer documentation. CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.’s documentation is mostly automated.

However handbooks that describe how one would create a theme, make a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party, use the REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. or automate things veia the CLICLI Command Line Interface. Terminal (Bash) in Mac, Command Prompt in Windows, or WP-CLI for WordPress. and so on don’t necessary receive updated documentation.

It requires all the handbook maintainers to know all the changes in each core release to be able to write something useful.

In some cases, the handbooks are updated but don’t necessary provide enough examples for new developers to get started.

There are gaps and we would like to close them.

Related material:
- BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Editor Handbook: https://developer.wordpress.org/block-editor/
- Common APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. Handbook: https://developer.wordpress.org/apis/
- Themes development handbook: https://developer.wordpress.org/themes/
- Plugin development handbook: https://developer.wordpress.org/plugins/
- REST API handbook: https://developer.wordpress.org/rest-api/
- WP CLI handbook: https://developer.wordpress.org/cli/commands/
- prubhtej 12:32 pm on May 25, 2020
  
  I have gone through the documentation. Is there any specific topic in the handbook or the documentation that need updation ?
  Hope to hear from you soon.
Marcio Zebedeu 6:31 pm on May 1, 2020

Project Name: Write your first WordPress Theme

Description:
It is not enough to say that creating a WordPress theme is easy if we do not show it in practice in the documentation. Currently we have a good article on how to start with WordPress, I believe we could do more to make the theme development manual better, as it does not provide a kind of tutorial that really ends with the creation of a functional theme.

Related Material
Link to the open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. project that needs documentation: https://wordpress.org/support/article
Updates to existing documentations:
https://developer.wordpress.org/themes/getting-started
It can be divided into stages: Creating a htmlHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. template, adding simple styles, separating those from html files and finally converting to one of the template for the WordPress theme

Want to get involved?

Weekly meetings

Season of Docs: A Call For Projects!

Mentors

Next Step: Project Ideas List

Want to get involved?

Weekly meetings

Mentors

Next Step: Project Ideas List

Share this: