advancedcustomfields/docs

docs's Issues

ACF Docs Migration Guide 2019

Hello awesome person 👋,

Please find below a comprehensive instruction guide for the ACF Documentation Migration Project 2019.

Contents

1. Project Overview
2. Progress
3. Technologies
4. Attributes
5. Content Types
6. Workflow
7. Notes

Project Overview

The ACF docs are in need of a "Spring Clean". Many articles are outdated, incorrect, inconsistent or missing entirely. The primary objective is to rewrite all articles with refreshed content / examples and consistent language / syntax.

A secondary objective is to migrate the ACF docs off WordPress and onto GitHub. This will open new opportunities for collaboration, performance and maintenance.

📘There are currently ~160 articles which can be found here.
📗Some of these articles have already been rewritten, which can be found here.

Progress

The progress of this project can be broken down into the individual doc categories:

• ⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️ Getting Started
• 🔵⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️ Field Types
• 🔵🔵🔵🔵🔵🔵🔵🔵⚪️⚪️ Functions
• 🔵⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️ Actions
• ⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️ Filters
• ⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️⚪️ Guides
• 🔵🔵🔵🔵🔵🔵🔵🔵🔵🔵 FAQ

Technologies

This project utilizes a few different technologies, the main of which is Markdown (used to write the doc content). I highly recommend reading the Mastering Markdown guide to refresh your skills.

Each doc also contains "meta" information. This is handled elegantly by a technology called Front Matter (YAML). Check out this Front Matter guide to better understand how it works. You can also see how ACF is utilizing front matter in this rewritten doc: Raw doc file > GitHub preview doc file.

Going back to markdown, ACF has the ability to add new rules in order to generate some of the custom HTML styling seen in the docs. For example, ACF is able to render an collapsible accordion element from the following text:

### This is the accordion title
This is the accordion text.
Multiple lines are fine.
The following line is the important one.
^^^

It is most likely that some of the docs will require new rules for custom content. Please let me know when you believe a new rule might be needed 🙂.

This being a public repository on GitHub, contributing is made easy via Pull Requests. GitHub have a great guide on Pull Requests here if you are not familiar with the workflow: https://help.github.com/en/articles/about-pull-requests

Attributes

Each doc contains the following attributes:

• title: (required) The doc title.
• description: (required) A short description, usually matching the first paragraph of content.
• category: (required) The doc category (getting-started, field-types, functions, actions, filters, guides)
• group: (optional) Some docs are grouped together. See the ACF Resources Page for examples.
• redirects: (optional) An array of slugs to create redirects from. See acf_register_block_type() for example.
• content: The doc content.

Content Types

The ACF documentation has been designed to speak to a number of different user types, from beginners to experienced developers. It is important to keep this in mind when writing content across the various categories.

Getting Started

These docs must be written with a "helpful" tone. Use basic examples and lots of screenshots. Don't allow the user to ask questions or make any assumptions, instead, spoon feed them all the information is an easy to follow manor.

Field Types

These docs are factual, and sit between a "Getting Started" guide and a "Function" technical doc. All field type docs should follow the same format and syntax as User Field:

• Description
• Screenshots
• Changelog
• Settings
• Template Usage

Functions

These docs are extremely technical. All functions docs should follow the same format and syntax as get_field():

• Description
• Parameters
• Return (optional)
• Changelog (optional)
• Examples
• Notes (optional)

Actions

These docs are similar to "Functions" in that they are technically minded. All actions docs should follow the same format and syntax as acf/save_post:

• Description
• Parameters
• Changelog (optional)
• Examples
• Notes (optional)

Filters

These docs are similar to "Functions" in that they are technically minded. All filters docs should follow the same format and syntax as acf/save_post:

• Description
• Parameters
• Changelog (optional)
• Examples
• Notes (optional)

Guides

Similar to the "Getting Started" docs, Guides should also be written with a "helpful" tone. Think of these as individual blog posts where a specific topic is covered from start to finish in an instructional way with examples. There is no set format for Guides, however, we should try to establish some consistency when possible.

Workflow

Each doc rewrite will require the following basic process:

1. Pull down the latest files from GitHub.
2. Find an existing doc from the ACF website. For example Action - acf/input/admin_head .
3. Create a new file using the category and URL slug: actions/acf-input-admin_head.md.
4. Create the Front Matter including title, description and category.
5. Following the advice mentioned in "Content Types", begin rewriting the doc.
6. Commit changes and Push to GitHub.
7. Create Pull Request with any comments to discuss.
8. @elliotcondon Review, Preview and Push to website.

Notes

• In some cases, it may be acceptable to simply copy the existing content or code examples. In this case, take the opportunity to perform some "Spring Cleaning" instead of a complete rewrite.
• All code examples should adhere to WP's coding standards (or close enough). Please use lots of code comments - for example: acf/save_post.
• Use the newly rewritten docs as a source of examples for any markdown or syntax decisions.

ACF Docs Contributors Guide

Welcome to the ACF Docs Contributors Guide, the primary resource for contributing to the Advanced Custom Fields Plugin Documentation.

Here you can learn about how the ACF Docs project is organized alongside instructions for creating content.

📂 Organization

Documentation for Advanced Custom Fields is maintained here on GitHub. These files are read by, and displayed on, the ACF Website via some magical code 🦄.

File Types

Docs are created as Markdown (.md) files. Markdown is a simple yet powerful text based language perfect for creating software documentation. More on this later.

File Names

File names may contain letters, numbers, dashes and underscores but may not contain spaces, uppercase characters or special characters.

In most cases the filename should directly match the URL slug for the doc. For example, if the doc URL is intended to be "xxx.com/resources/getting-started-with-acf", the doc filename should read "getting-started-with-acf".

Filenames should also closely match the title of the document. In some cases this may not be possible. For example, the action "acf/save_post" contains a forward slash in the title which would cause issue with the file structure. In this case, convert / to _ and resolve to "acf-save_post".

File Structure

Documentation is split into six categories. Each doc file should live within its corresponding category folder.

📂 getting-started
   📄 this-is-a-guide.md
   📄 this-is-another-guide.md
📂 fields
📂 functions
📂 actions
📂 filters
📂 guides

Assets

All assets such as images should be placed in the 📂 assets folder using a naming convenstion to avoid duplicates such as acf-checkbox-field-interface.png or acf-checkbox-field-settings.png.

To find the GitHub URL of an uploaded image, navigate through the source files on GitHub and copy the image location URL when previewing the image.

To avoid large file sizes:

• Use the .png file type for screenshots that do not feature artwork.
• Use the .jpg file type for screenshots that do feature artwork.

✍️ Markdown

Markdown is a simple yet powerful text based language perfect for creating software documentation. Be sure to checkout the Mastering Markdown guide for more information and syntax examples.

Markdown is also deeply integrated into GitHub, meaning you can preview the generated HTML from within the repository without needing to perform any build process.

We use Markdown to structure content using headings, lists, links and more.

Front Matter

Markdown even has it's own "meta" solution called Front Matter, a code-block of YAML found at the beginning of the .md file. Tip: GitHub displays this meta in a table when previewing a doc.

This is a Be sure to check out the Front Matter guide to better understand how it works. You can also see how ACF is utilizing front matter in this rewritten doc: Raw file = Preview file.

We use Front Matter to add titles, descriptions, status and more.

📄 Content

The ACF Docs are an official guide for the ACF plugin. They are read by thousands of people, from all across the world, many of whom may not know the intricacies of how the plugin works.

In order to ensure the best experience possible, the ACF documentation should be welcoming to inexperienced readers whilst useful to the experienced ones. Content should be written in a clear & concise tone, and all efforts should be made to ensure accuracy & consistency throughout.

Tone and Voice

Tone refers to the mood or attitude of a specific piece of writing. For example, your tone in a personal email might be more informal than one you send at work. Voice reflects overarching characteristics that shouldn’t change much between documents. The voice of ACF and its community is friendly but professional.

Be friendly: In English, use contractions (I’m, don’t) and write in the second person. Use language that is accessible to your target audience. Avoid jargon.

Be professional: While writing in a friendly, accessible manner, be sure not to overdo it. Don’t use too many exclamation marks, and don’t use slang or web shorthand. Write concisely and use the active voice whenever possible.

Users search the documentation for the answer to a question. Maintain a friendly, informal tone, but focus on being clear, concise, and very precise. Get to the point as quickly as possible. Explain technical terms, but be careful not to be condescending. To ensure clarity, start by briefly specifying the context of the current topic.

Keep in mind that many users are not native English speakers. Avoid long narrative paragraphs. Keep paragraphs short and focused, with consistent vocabulary and phrasing that is easy for all your readers to understand.

✅ Good example:

On the left side of the screen is the main navigation menu listing the administrative functions you can perform.

❌ Bad example:

If you peek over at the left side, you’ll see a menu called main navigation, which is the main menu. This menu is a list of functions you as the administrator can do from the administration screen.

Syntax

Keep the following points in mind when writing documentation for ACF. These will help keep coherency across the project.

Headings

• Use Title Case for h1 and h2 headings and Sentence case for h3 and h4 headings.
• Avoid punctuation in headings.

Lists

• Every bullet is a full sentence, and ends with a period.
• Keep sentence structures parallel across bullets.

URLs

It's very likely that at some point you will want to link to other documentation pages. It's worth emphasizing that all documents can be browsed in different contexts:

• ACF website.
• GitHub website.

The ACF website does not yet contain the ability to modify URLs, so please use the full URL when possible.

• When linking to existing documentation, please use the full URL to that doc on the ACF website: https://www.advancedcustomfields.com/resources/user/
• When linking to an image hosted in this repo, please use the full URL to that asset on GitHub: https://raw.githubusercontent.com/AdvancedCustomFields/docs/master/assets/acf-user-field-interface.png

Structure

With the exception of long-form unique Guides, ACF documentation should follow a consistent structure. This aims to improve the reading experience by organizing content for easy digestion.

The following table depicts the heading (h2) structure used for the various content types. Please note that not all headings are required.

Category	Heading Structure
Getting Started	n/a
Fields	Description, Screenshots, Changelog, Settings, Template Usage, Notes
Functions	Description, Parameters, Return, Changelog, Examples, Notes
Actions	Description, Parameters, Changelog, Examples, Notes
Filters	Description, Parameters, Changelog, Examples, Notes
Guides	n/a

When writing content under each of the aforementioned headings, please keep a consistent format to the existing documentation. For example, parameters are written in a specific way. Be sure to refer to existing documentation for examples.

Attributes

All docs contain attributes, created using Front Matter at the beginning of each .md file.

Attribute	Description
title	The doc title
description	A short description, usually matching the first paragraph of content.
category	The doc category (getting-started, field-types, functions, actions, filters, guides)
group	(Optional) Some docs are grouped together. See the ACF Resources Page for examples.
redirects	(optional) An array of slugs to create redirects from. See acf_register_block_type() for example.
version	Not added yet.

🧩 Code

At the heart of ACF documentation is its code examples. Being a developer tool in the WordPress space, ACF has a diverse user-base including both the hardcore devs and the DIY-ers.

It is important that our documentation speak to both in a helpful and professional manor.

Assumptions

It is fair to make some assumptions about the reader. We should assume that the reader has basic knowledge of the PHP language and experience with editing WordPress templates.

To elaborate on this point, things like if statements, foreach loops and variables should not need to be explained. However, things like ACF functions and ACF concepts should be explained in detail.

Coding Style

The ACF docs should feature a consistent coding style inline with modern PHP theme development and WordPress' coding standards. Note that WordPress' PHP coding standards are not a requirement but act as a good reference.

Furthermore, code examples should respect the context of where the code will be used. Use the standard curly brace syntax for code examples that will be used in the functions.php file:

if( $foo ) {
	return 'bar';
}

... and use alternative syntax for code examples that will be used in other template files (such as single.php):

<?php if( $foo ): ?>
<p>Bar</p>
<?php endif; ?>

Write readable code

Dylan Brigman wrote a great article on Writing highly readable code which covers a neat example of refactoring a code snippet to become more readable. In essence, write code in an easy to follow manor using meaningful variable names and comments.

Write meaningful comments

Code comments provide a helpful voice to narrate your code. There is a fine art to writing meaningful comments without it being overdone or just plain redundant.

❌ Bad example:

// Get the country code.
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);
 
// If country code is US.
if ($country_code == 'US') {
 
    // Display the form input for state.
    echo form_input_state();
}

When the text is that obvious, it's really not productive to repeat it within comments. If you must comment on that code, you can simply combine it to a single line instead:

✅ Good example:

// Display state selection for US users.
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);
if ($country_code == 'US') {
    echo form_input_state();
}

Assets for ACF Blocks