However, with this convenience comes a paradox of choice. There is often too much information to choose from.

When you want to learn about a particular web development topic, you may wonder which path to take. Should you read a blog post about it or dive into the developer documentation? In this blog post, we’ll explore the differences between the two and help you decide which one to choose.

Web Development Blog Post vs. Developer Documentation

First, let’s define what we mean by a blog post and developer documentation. A blog post is an informal article written in a conversational tone that aims to educate, entertain or inform readers about a particular topic. It is usually written by an individual or a group of individuals and may offer a unique perspective or point of view on a topic.

Web developer documentation, on the other hand, is a technical document that provides detailed information about a product or service. It’s usually written by the product creators or developers and is intended to help users understand how to use the product or service effectively.

So, when should you read a blog post versus the developer documentation? Well, it depends on your goal and the information you need.

When to Read a Blog Post

If you are looking for insights or best practices from WordPress development experts who have used the product or service, blog posts can be a valuable resource. Blog posts are usually written by professionals who have hands-on experience with the technology and can provide real-world examples and advice on how to use it effectively.

Also, blog posts are ideal when you’re looking for a general understanding of a web development topic or want to learn from someone’s personal experience. For example, if you’re interested in learning about the benefits of Headless WordPress, a blog post could offer you some personal insights into how Headless WordPress has helped the author’s clients. Or, if you’re interested in learning about an alternative way to debug React, a blog post written by a senior backend engineer could give you some valuable insights and tips.

Benefits of Reading a Blog Post

Blog posts can be an excellent way to get started on a web development topic, and they’re often written in a more conversational tone, making them easier to understand. They can also be a great way to learn about a topic from someone who has experienced it first-hand, which can make the learning experience more relatable and engaging.

In our software world, blog posts can also be an excellent source of information for staying up-to-date with the latest trends and developments in the software industry. For example, if you are interested in learning about a new programming language or framework, reading blog posts from experts in the field can help you stay informed and ahead of the curve.

I want to give you an example of some blog posts about one of our flagship products, the Custom Post Type UI Plugin, this type of article allows you to stay up to date on the latest news about this product from another’s point of view person or expert:

• The History of Custom Post Type UI
• Custom Post Type UI Supports WPGraphQL
• How to Create WordPress Custom Post Types With Plugin

When to Read Developer Documentation

Documentation, on the other hand, is ideal when you need specific information about a product or service. If you’re figuring out how to use a new technology or software, documentation is the best place to start.

Designed to be technical and comprehensive, developer documentation provides everything you need to know in one place. This includes the features, functions, and capabilities of that product or service.

Documentation can be particularly useful when you’re trying to troubleshoot or need to understand a specific feature or functionality. It’s also helpful when you’re looking for step-by-step instructions.

Developer documentation is typically written by the software vendor or publisher, so it is generally reliable and updated. It also covers all the essential topics and features of the product or service. This ensures you have a good foundation to build upon.

Based on the blog post example above, here is the documentation of the same product.

Conclusion

When choosing between a web development blog post and developer documentation, it’s important to consider your goal. A blog post is the way to go if you are looking for:

• General Information
• Expert or Personal Insights
• Real-World Examples
• The Latest Industry Trends

If you need specific information or step-by-step instructions, developer documentation is the way to go.

It’s worth noting that both blog posts and documentation can be valuable learning tools, depending on your needs. Ultimately, it’s up to you to decide which one is the best fit for your learning style and goals.

The post Understanding Web Development: When to Read a Blog Post or the Developer Documentation appeared first on WebDevStudios.

SassDoc is to Sass what JSDoc is to JavaScript: a documentation system to build pretty and powerful docs in the blink of an eye.
– SassDoc.com

So your team is using Sass, and everybody is whipping out amazing @mixins, @extends, custom functions, and maximizing use of all those wonderful, built-in Control Directives (@if, @for, @each, @while). Your team has a system in place for introducing new @mixins to other team members so everybody leverages the goodies. While each team understands each project’s Sass nuances and intricacies, there can be gaps in understanding for team members that are added, or even newly hired employees. This is where the often dreaded documentation can come in handy.

Projects like thoughbot’s Bourbon and Bourbon Neat generate and run their documentation site’s on SassDoc.

Install SassDoc

These instructions assume you’re running Grunt, but SassDoc has documentation on other task runners, like Gulp. You could also just install SassDoc globally as a Node package, with:

# Install SassDoc globally
npm install sassdoc -g

And here is how I would do it (again, with Grunt):

npm install --save-dev grunt-sassdoc

Once the plugin is installed in your desired project be sure to add it to your Gruntfile.js.

grunt.loadNpmTasks('grunt-sassdoc');

And you can now run SassDoc with:

grunt sassdoc

Here is an example of a simple configuration for your Gruntfile, but there are plenty of other options to choose from:

// Tip: you're not required to pass every options,
// just set the one you need.
grunt.initConfig({
  sassdoc: {
    default: {
      src: 'path/to/source',
      options: {
        dest: 'path/to/docs',
        display: {
          access: ['public', 'private'],
          alias: true,
          watermark: true,
        }
      },
    },
  },
});

Writing SassDoc Compliant Comments

With SassDoc installed, we’re ready to start writing our Sass documentation and generating our custom site. Here is an example of some SassDoc compliant comments I wrote on a simple mixin:

// ----------------------------------------------------------------------

  // Margin auto

// ----------------------------------------------------------------------

////
/// @author Damon Cook
/// @group wds
////

/// Horizontally center a block element
///
/// @example scss - Basic Usage Sass
///    .center-my-block-thingie {
///        @include margin-auto();
///    }
///
/// @example scss - Basic Usage CSS Output
///    .center-my-block-thingie {
///        margin-left: auto;
///        margin-right: auto;
///    }

@mixin margin-auto {
    margin-left: auto;
    margin-right: auto;
}

Mostly it is just a matter of using three forward slashes to denote your SassDoc comment block, e.g. ///. Next, you’ll want to brush up on all the Annotations SassDoc has available: http://sassdoc.com/annotations/

#proTip: Use @group to Organize Your Entries

Since we include and use Bourbon Neat in our wd_s project starter via Bower, it is possible to generate and output Neat’s already included SassDoc comments in your project’s SassDoc site. Here is what I used in my Gruntfile on a recent project:

sassdoc: {
    default: {
        src: [
            'themes/custom-theme/sass/**/*.scss',
            'bower_components/bourbon/app/assets/stylesheets',
            'bower_components/neat/app/assets/stylesheets'
        ],
        options: {
            dest: './sassdoc/',
            display: {
                access: ['public'],
                watermark: false
            },
            groups: {
                wds: 'WebDevStudios',
                'undefined': 'Bourbon & Neat'
            },
        },
    },
}, 

Then I use the @group annotation to denote internal documentation vs Bourbon’s, like so:

/// @group wds

Which then outputs our SassDoc site to organize entries like so:

It is a bit of a workaround, and I would prefer that Bourbon’s maintainers included an @group bourbon in their SassDoc comments, but for now this works.

SassDoc Themes, and beyond

By default SassDoc comes with a handy theme, but also provides documentation on creating your own.

Hopefully, you’ve considered implementing some Sass documentation in your next project, and now have the tools to do so. Writing the documentation can add some additional overhead, but encourages consistency and increase knowledge sharing within teams.

Also, stay tuned–I’ll be updating this post in coming weeks as we roll out integration of SassDocs into our wd_s starter project.

The post Getting Started with SassDoc appeared first on WebDevStudios.