Tag: documentation

Everyone, everyone, hates doing it. We all do.

But there’s something that blogging regularly has brought me that is specifically related to documentation. And it’s this.

I am more likely to write down exactly how I solved a problem if I think about it as a new blog post.

I know, that sounds so simply it’s stupid, but I’ve realized that the whole reason I’ve figured all these things out is that I want to have something to blog about, and I want the blog posts to be interesting, so I started writing down how I solved problems.

Of course, the joy of a problem is in the solving, so most of the time I’m talking about happy things. I do also blog about my failures, my missteps, and my totally-wrongs. Nothing wrong with being wrong. You learn a lot more from it, I feel.

Start Without Code

When I start ‘figuring out’ a thing, I write it down without any code. I write down “I want to do X.” And then I start brain storming.

Take Monday’s post about term icons. “I want to assign an icon to a term.”

That’s how it started. Then I talked through my vague concepts:

• Show the icon on the back end
• No uploading icons
• Show the icon on the term edit and terms list page
• Make sure it can show on the front end

It’s really just the broad ideas. I’m not digging in deep.

Pick Something Easy

When I start coding, I pick the thing I already know how to do the most of. In this case, it was showing the icon on the front end. That let me start in comfort. I uploaded the images to the development server (VVV in this case) and started messing around with showing the images on the front end.

I hardcoded in everything at first, using a default icon of ‘bacon’, and went about figuring out how I wanted it to display. I didn’t document this as much since it really was just about the look first. I knew when I got down to brass tacks, I’d be doing this:

	<ul class="myterms-list"><?php
		$terms = get_the_terms( $show_id, 'my_terms' );
		if ( $terms && ! is_wp_error( $terms ) ) {
			// loop over each returned cliche
			foreach( $terms as $term ) { ?>
				<li class="show myterm myterm-<?php echo $term->slug; ?>">
					<a href="<?php echo get_term_link( $term->slug, 'my_terms'); ?>" rel="show cliche"><?php
						$icon = get_term_meta( $term->term_id, 'my_termsmeta_icon', true );
						$iconpath = get_stylesheet_directory().'/images/symbolicons/'.$icon.'.svg';
						if ( empty( $icon ) || !file_exists( $iconpath ) ) {
							$iconpath = get_stylesheet_directory().'/images/symbolicons/bacon.svg';
						}
						echo file_get_contents( $iconpath );
						echo ' '.$term->name;
					?></a>
				</li><?php
			}
		} ?>
	</ul>

All of that code, except the icon part, was already written. That’s why it was easy.

Pick Something Obvious

Once I’ve done something easy and boosted my confidence, I start with the actual work. How do I set a term meta for a custom taxonomy?

I knew how to make custom meta boxes, but taxonomies were different. I quickly remembered all the work Boone did for WordPress 4.4 and read his post on the Taxonomy Roundup. That way I learned that, as I had assumed, get_term_meta was a thing.

Then I check to see if CMB2 knew how to use term meta, and happily found that it will work with term meta out of the box. No extra work. Thus the obvious became simple and I made a custom meta box for my term to put in a plain text field which was (originally) the path to my media file.

I used that process to start the blog post. That was the new thing, so I wrote up the answer, not the process, and explained how to do the thing.

Write About the Tweaks

At that point, all that was left was busy work. I added in how to show the images on the back end, but then… then I did something extra. As I wrote the end of the post, I asked myself what the next logical step was? Well that would be not letting someone typo or put in names of images that didn’t exist. Instead of having to document all the images, I could just show a list.

And that’s what I did.

Share It

This is actually universal.

If you just documented something, you either did it so you can repeat the process over and over, or so you could have someone else do your dirty work for a change.

If it’s personal, change ‘share it’ to ‘store it in an accessible place.’ Something in the cloud will do in a pinch. I often have my little things in a DropBox folder called “How Do I…” That’s because I usually ask “How do I edit all the images for …”

But if it’s not personal, if I know a group will have to do it again later, I document it and share it. It may go in the company internal knowledge base or maybe it’ll be on a GoogleDoc shared with the people who need to know. Maybe I’ve put it on this blog.

Either way, I documented. I released it.

Now it’s your turn.