Write the Docs: Tom Christie — Designing MkDocs

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Tom started day 2 of talks at Write the Docs. He works as a soft­ware engi­neer at a web devel­op­ment startup in Brighton, UK.

MkDocs is a soft­ware project for pro­duc­ing nice-looking doc­u­men­ta­tion from mark­down files. Tom uses it with a lot of his own open source projects. Previously he han­dled doc­u­men­ta­tion through Sphinx, which Markus talked about yes­ter­day. This uses restruc­tured text for doc­u­men­ta­tion. Writing the actual docs, though, was not the most attrac­tive process.

To help cre­ate more attrac­tive docs with a clearer design Tom started draft­ing docs in Markdown. As he said, “The doc­u­men­ta­tion is really the design of the prod­uct.” Using edi­tors like Mou he was able to cleanly assem­ble and visu­al­ize his doc­u­men­ta­tion. It helps to see what your read­ers will see.

From that expe­ri­ence he decided to tear up the exist­ing tools and start again. Writing a cus­tom lit­tle script he built the doc­u­men­ta­tion for the django REST frame­work. The down­side was that every­thing was hard-wired to this one project; it wasn’t the most reusable piece of code. Tom sought a more reusable solu­tion; thus, MkDocs.

MkDocs is writ­ten in Python so you’ll need to install that as well as pip. Once installed you can cre­ate and start run­ning a new doc­u­ment project. New projects start with a sin­gle con­fig­u­ra­tion file, where all set­tings are optional, and a /docs direc­tory which con­tains the Markdown source files. From a clean demo MkDocs han­dles pre­sent­ing the docs in a nice, clean-looking design. Built-in is live reload­ing; so any­time you edit an under­ly­ing doc­u­ment the site will reload upon sav­ing. There’s no build process or deploy­ment that needs to happen.

The docs direc­tory han­dles all your doc­u­men­ta­tion source. While it requires an index.md file you can include images, other media, and any CSS or JavaScript to tweak the basic theme. Theme’s all change on the fly and don’t impact the doc­u­men­ta­tion con­tent. It takes just one line in the con­fig­u­ra­tion file to change the design.

You can also inter­link all the docs with reg­u­lar hyper­links within Markdown. You can also use rel­a­tive links, though, if you’re work­ing within your doc­u­men­ta­tion folder. You can also use ref­er­ences to tar­get a page or title any­where in the documentation.

To push your doc­u­men­ta­tion site live to a server you can run mkdocs build and MkDocs will cre­ate a sta­tic HTML site with your con­tent, theme, and all nec­es­sary resources. Since it’s sta­tic HTML you can deploy it on any server or even GitHub Pages. There’s some GitHub Pages inte­gra­tion baked in to MkDocs that lets you run one com­mand, gh-deploy, and let the soft­ware build a full GitHub Pages site for your project.

The 1.0 release for MkDocs is in-progress. You can help Tom make it hap­pen by con­tribut­ing on GitHub.

Write the Docs: David Hooker — What I have taught developers about writing

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

David wrapped up day one of the con­fer­ence. He works as the writer at Prezi and han­dles the knowl­edge base, the engi­neer­ing blog, and pretty much any­thing you see with words and Prezi.

In some way, shape, or form com­mu­ni­ca­tion can let us down. A belief in doc­u­men­ta­tion is a belief that com­mu­ni­ca­tion can be improved through writ­ing. You’ve cre­ated some­thing you’re proud of and you want to share it with the world so that they use it.

The best way to engage someone’s inter­est is to hook on to emo­tion. Your words are what allow you to do that.

David out­lined 4 rules for draw­ing upon someone’s emotions:

  1. Start with the good shit. Don’t start with the back­story, start with what’s interesting.
  2. Keep it sim­ple. There’s lots of places where com­plex writ­ing can go wrong.
  3. Write what peo­ple actu­ally say. Usage trumps any of the rules; for­mal lan­guage rules are just that, formal.
  4. Don’t repeat. Repetition in speech sounds great, but the eye doesn’t like it.

You can choose to make your writ­ing excit­ing. No one needs to be able to tell that an engi­neer wrote your documentation.

WordCamp Portland: All about post formats

Today I gave a talk at WordCamp Portland about post for­mats and how they make your site awe­some. The slides are posted below and some handy links are included as well. Enjoy.

The WordPress Codex has some ter­rific infor­ma­tion on what for­mats are and how they can be imple­mented in case you need more details after this talk. Ian Stewart also gave a great talk about this at WordCamp San Francisco which I wrote some notes about before.

WCSF: How the web works with Jeff Veen

Jeff Veen opened Sunday’s ses­sions with a talk about how the web works. He started with a story about beer and how 200 years ago the only way you could have a cold beer was if it was win­ter or if you were rich and could trans­port and store ice.

Frederic Tudor was an entre­pre­neur who turned ice into a busi­ness. He became quite prof­itable and later real­ized that he could make a greater for­tune by ship­ping that ice to the Caribbean and all over the world.

Technology marched on and peo­ple found ways to cre­ate ice in ware­houses that did not need to be shipped. It could be stored and cre­ated locally. The com­pa­nies that were suc­cess­ful ware­hous­ing ice did not suc­cess­fully tran­si­tion to ice in the home. Newer entre­pre­neurs eclipsed the tra­di­tional businesses.

A sim­i­lar thing hap­pened with gold trans­porta­tion. Wells Fargo and American Express were experts in the stage­coach busi­ness. However, they antic­i­pated the changes com­ing and restruc­tured their busi­nesses around the con­veyance of infor­ma­tion instead of the ship­ping of phys­i­cal goods. They made this tran­si­tion rapidly too, need­ing only a few days.

So the ques­tion is, are we build­ing com­pa­nies like the ice ware­houses or like the gold busi­nesses? How do we know which path our busi­ness will take?

We’re in a sim­i­lar sit­u­a­tion now where incum­bents are los­ing ground to ser­vices like Hulu, Spotify, and Pandora who are native to the web. The same thing is hap­pen­ing with typography.

The abil­ity to embed web fonts has rev­o­lu­tion­ized the model that foundries have relied upon as their busi­ness. This is what Jeff is doing at Typekit. They’re try­ing to help foundries be like the gold com­pa­nies and less like the ice warehouses.

So as we look back we real­ize that the ice indus­try was less about ice and more about health. The gold indus­try was not about mov­ing bul­lion from San Francisco to New York but was about trans­form­ing wealth into data that could be com­mu­ni­cated. Likewise, media is not about sell­ing assets but is rather about ser­vices that make con­sump­tion seamless.

The qual­i­ties that con­tribute to the suc­cess of the web are also what will make us successful.

On the web the thing that wins is that which gen­er­ates rough con­sen­sus and has run­ning code. It’s the code in people’s hands that ulti­mately is suc­cess­ful. The first per­son out with run­ning code in front of users can gen­er­ate momentum.

Jeff also quoted Jeff Atwood who says:

The veloc­ity and respon­sive­ness of your team to user feed­back will set the tone for your soft­ware, far more than any sin­gle release ever could.

Jeff Veen uses Twitter to see if the code deploys they’ve made that day are impact­ing the expe­ri­ence of users in a pos­i­tive way. Iteration will get you closer and closer to perfect.

In other words, “The speed of iter­a­tion beats the qual­ity of iteration.”

We’re putting our most valu­able mem­o­ries on the web with Flickr. We’re also cre­at­ing a col­lab­o­ra­tive record of human his­tory with Wikipedia. The web is not dead, in fact it’s never been more vibrant or suc­cess­ful. To keep it that way we need to pro­tect and advo­cate our open sys­tems and avoid the walled gar­dens sold on a bro­ken con­cept of safety.

Geocities is an exam­ple of these walled gar­dens which can just be shut down by a sin­gle com­pany. As Jeff said, “There are lit­er­ally peo­ple who don’t give a shit about the web.” That’s who we need to pro­tect the web against.

WordCamp St. Louis: It’s about time. It’s about type!

Mary Baum was one of the last ses­sions of the after­noon and was talk­ing about typog­ra­phy on the web. Mary has a long his­tory in design and typog­ra­phy and believes it’s about damn time we have full access to type on the web.

The web-type drought

Up to recently we have all be frus­trated by the lim­ited typo­graph­i­cal options we’ve had for 15 long years. 5 choices is not enough, it’s time we had more.

Mary pin­points the web-type drought end­ing on the day Paul Irish posted his work on @font-face in September of 2009. He saved us. :)

We came from a time of Times, Georgia, Verdana, Trebuchet, and Tahoma. Now we thank­fully have tons of options with dif­fer­ent type­faces. Embedded OpenType has been around since 2004 but it’s only till recently that type foundries have opened up licenses for use on the web.

Background with WordPress

Mary just got started with WordPress within the last year but in that time has put hun­dreds of hours into learn­ing WordPress themes and just enough PHP to be dan­ger­ous. She got started with the Thematic frame­work but is now work­ing with the Genesis frame­work but also uses Elegant themes for some sites.

Type options

Cufón, sIFR, Typekit, fonts.com, Google web fonts are all options that we have now for using type­faces in our sites. There’s plenty more but those are the ones Mary pointed to as worth using and, in some cases, pay­ing for.

All those hosted solu­tions are good but Mary still prefers going the route of using your own fonts on your own server using @font-face. One thing to be care­ful of though is upload­ing the license infor­ma­tion to your own server as well so that it’s clear you have the rights to use that font on the web.

When using @font-face you want to be care­ful to make sure you have a bul­let­proof CSS set up for your font. Fontspring posted an updated ver­sion of bul­let­proof CSS to use that will cover all the way back to IE6.

WordCamp St. Louis: The Anatomy of a Premium WordPress Theme

Brian Fegter gave a talk in the after­noon dis­cussing WordPress pre­mium themes. Brian runs Mister Nifty where he works with churches of all sizes on their tech needs.

He got started by cov­er­ing the truth about com­mer­cial themes. As he says:

There is not one sin­gle theme that does not require sup­port. You must build a sup­port system

Brian also believes that soft­ware devel­op­ment needs to be for the cus­tomer. This is why sup­port and doc­u­men­ta­tion are so impor­tant. As he pointed out, a pur­chased theme rarely stays in its orig­i­nal condition.

Having a solid tem­plate archi­tec­ture is also fun­da­men­tal to cre­at­ing a good pre­mium theme. Brian pointed to the WordPress Codex for infor­ma­tion on theme devel­op­ment and tem­plate hierarchy.

Brian set down a credo for prop­erly devel­op­ing a theme. He believed that you should:

  • fol­low tem­plate hier­ar­chy patterns
  • clearly name sup­port­ing files and folders
  • never, never, ever, never, ever nest a plu­gin inside a theme
  • clar­ity over cleverness

WordPress assets are your friend when cod­ing a theme. There’s a lot that is built in to WordPress which will let you eas­ily enhance a com­mer­cial theme with­out a large code foot­print. The main things dis­cussed were:

  • clearly named sidebars
  • cus­tom post types only when necessary
  • define theme loca­tions for menus
  • local­ize your strings
  • set WP image sizes vs image resiz­ing scripts
  • lever­age the power of CSS with body_class() and post_class()

He also showed off some cool func­tion­al­ity in the UpThemes frame­work that’s avail­able on Github. There’s lots of sweet stuff built in there for Google fonts and more.

In some ways code is nar­ra­tive. Your theme tells a story and has an intended result. The back-end code should clearly nar­rate the story of the front-end dis­play. All this helps because clean code lever­ages the brain to quickly iden­tify and asso­ciate words with functions.

Functions though need to use pre­fixes and should only try to accom­plish one thing. If any func­tion includes things that can be spun out into a sep­a­rate func­tion then they should be spun out that way. For code com­ments with func­tions Brian says that:

If it’s nec­es­sary to com­ment about how a func­tion works, your code stinketh.

It’s also a good idea to use built in func­tion­al­ity for things like browser detec­tion and con­tent fil­ter­ing. This keeps you from hav­ing to add lots of server over­head and user frus­tra­tion. In other words, we should be cre­at­ing use­ful code, not dupli­cate code.

WordCamp St. Louis: WordPress for Writers and More

Shawntelle Madison gave a talk at WordCamp St. Louis titled “WordPress for Writers, Publishers, and other Content Providers.” Shawntelle is an urban fan­tasy writer with a new book com­ing out. She also works with design firms in St. Louis and has been work­ing with WordPress for over 5 years.

With her book com­ing out Shawntelle has seen both sides of the coin with what pub­lish­ers require from author websites.

WP in the pub­lish­ing community

It’s a lot more preva­lent than you first think. Shawntelle polled 47 authors from var­i­ous gen­res and 85% were using WordPress. The user-friendly Dashboard, ease of theme changes, and flex­i­bil­ity with wid­gets and plu­g­ins were favorites.

They also like it because it’s far eas­ier than cod­ing a site from scratch. When your job is writ­ing con­tent you don’t want to be spend­ing all the time cod­ing and design­ing your site.

Branding

Shawntelle said that “brand­ing is very impor­tant for authors.” The design is what read­ers first see and it should really fit with the genre of your writing.

A great exam­ple is Scott Westerfeld who has a site which fits his steam­punk style writ­ing quite well.

What’s com­mon

Authors expect a few key fea­tures for almost every site. They like hav­ing things like:

  • Newsletter inte­gra­tion
  • The abil­ity to add a back­list of books
  • Integration with social media
  • Other basics like ad man­age­ment, con­tact forms, and a well-designed blog

Most authors Shawntelle works with already have had some expe­ri­ence with WordPress. They don’t want a com­plex front-end lay­out and pre­fer to keep things simple.

Determining who is respon­si­ble for site main­te­nance is key to any project you work with an author on. Many won’t keep the site updated so fig­ur­ing out who will be respon­si­ble for that going for­ward is crucial.

Shawntelle also men­tioned some of her favorite and most use­ful plu­g­ins from projects with authors.

Publishers

Out of the 6 big pub­lish­ers 2 are run­ning WordPress in their work.1 Random House and Hachette use WordPress to power parts of their imprint on the web.

For exam­ple, Random House uses WordPress to power their At Random site. There’s tons of reader guides, audio and video, as well as links to the books in the Random House catalog.

Data from the exist­ing Random House cat­a­log was used to power things like the New Releases slider and more on the site. They also link up to ser­vices like Goodreads, Shelfari, and LibraryThing.

  1. The big 6 are Macmillan, Random House, Penguin, Simon and Schuster, Hachette Books, and HarperCollins.

Challenging Traditional WordPress Design

Catherine Winters had the sec­ond ses­sion in the after­noon UX track. She talked about how to expand our con­cep­tion of what a WordPress site is.

Oftentimes many of us can tell, at a glance, when a site is using WordPress.” It’s the ones that sur­prise us that make things inter­est­ing. What is good for a blog is not nec­es­sar­ily best for other sites.

The assump­tion is that peo­ple mak­ing web­sites already know what they’re doing. This isn’t nec­es­sar­ily true. Elements taken as a given on a blog (side­bar archives, blogroll, etc.) should be recon­sid­ered. Many times they aren’t nec­es­sary to the over­all func­tion­ing of the design.

Catherine argues that we should try to limit things in sites that are nec­es­sary to the site itself. By doing this we’ll be able to avoid what Jakob Nielsen refers to as ban­ner blind­ness.

She points out that “The blog post is the pitch.” The con­tent of a site is what peo­ple will stick around for. Badges and wid­gets in the side­bar dis­tract from this cen­tral purpose.

Similarly, page nav­i­ga­tion and forc­ing users to click-through to see full con­tent only cre­ates a drop in the per­cent­age of users who do stick around to read things.

Looking to the design of apps like Readability or Instapaper that are cen­tered around read­ing can serve as effec­tive guides for sites. She also pointed to Dustin Curtis and Jason Santa Maria as exam­ples of effec­tive con­tent design and direction.

Others, like the ADDitude site that Catherine men­tioned are exam­ples of all the things to avoid. 9 col­umn grids with busy design that pro­vides no sense of hier­ar­chy just over­whelm us.

wp-Typography was also men­tioned as a way to align a site with basic typo­graph­i­cal prin­ci­ples. This pro­vides some basic tools for hyphen­ation, bul­lets, and other typo­graph­i­cal tools.

Making Custom Theme Options Easy

Toby Mckes, a WordPress devel­oper at I Can Has Cheezburber, gave the sec­ond talk at WordCamp Developers on the theme options pan­els their sites use. CheezCAP is the cus­tom theme options panel they’ve open sourced.

Cheezburger runs over 50 sites on WordPress.com VIP. CheezCAP, which stands for Cheezburger Custom Administration Panel, makes their deploy­ment process for themes really simple.

Background

The inter­net is a series of tubes filled with cats. Toby started on the farm team at Cheezburber where they were putting out many sites every week. The goal was “OMG moar sites plz.”

Their ini­tial theme deploy­ment process was ter­ri­ble. Toby had to spend half his time as a server admin. On Thanksgiving 2009 one of their sites was posted to the Guardian UK and hit 700,000 pageviews. He got to spend his Thanksgiving reboot­ing the server.

They also didn’t have ver­sion con­trol. There was no way of track­ing what was being changed and many sites were hacked together to the point of look­ing pretty bad. It was easy to make new sites but dif­fi­cult to update and main­tain them. They switched to a uni­fied theme on WordPress.com.

Early on they had 10 sites run­ning this uni­fied theme and one file which con­tained all of the cus­tomiza­tion options for the sites. CheezCAP was the solu­tion to make this easier.

CheezCAP

Licensed under the GPL v2 CheezCAP adds an options panel to make cus­tomiza­tion easy. There’s a pre-configured con­fig file that you can cus­tomize to your lik­ing. Its core con­tains a few key aspects:

  • Boolean options cre­ate as basic tog­gle switches.
  • Text options can rep­re­sent alphanu­meric strings to be inserted.
  • Dropdown options serve as more com­plex options.
  • User caps to limit edit­ing abil­ity to spe­cific user roles.

All of this goes right into your Dashboard and lets you get new sites set up and run­ning with cus­tom options that require minor con­fig­u­ra­tion changes. Google Analytics inte­gra­tion, A/B test­ing, cus­tom 404 pages, and much more can all be con­fig­ured with CheezCAP.

The killer fea­ture of all this is import/export. All of these options can be exported from one site and seam­lessly imported into a new site. Setting up devel­op­ment sites is super easy using this.

Update: Toby gave a sim­i­lar talk at WordCamp Seattle and will be updat­ing the slides from that talk.

HTML5 and CSS3 with WordPress

Ray Villalobos, who flew all the way out from Florida, opened the devel­op­ment track at WordCamp Developers with a talk about HTML5, CSS3, and WordPress inte­gra­tion. He posted his slides before the talk as well.

Ray is an author at Lynda.com and runs a course on iOS 4 and web appli­ca­tions. The WordCamp pre­sen­ta­tion grew out of this course. He works for Entravision Orlando full-time, which man­ages many Univision stations.

The talk cov­ered core HTML5 and CSS3 con­cepts and how they can be imple­mented into your WordPress development.

Core con­cepts

Ray described HTML5 as a bit of a rebel­lion against XHTML 2.0. In other words, “XHTML 1.1 makes humans code like machines.” With its flex­i­ble pars­ing rules, sup­port of exist­ing code struc­ture, and com­mon tags HTML5 respects users, browsers, and lets peo­ple write code in a more fluid manner.

HTML5 brings sup­port for seman­tic ele­ments (header, footer, asides, etc.) along with rich media and new form elements.

The seman­tic tags in HTML5 were cre­ated by ana­lyz­ing the tags peo­ple were already using in their markup. The goal was to make things eas­ier and pro­vide for more rapid prototyping.

CSS3

Mobile browsers have great sup­port for CSS3. Mobile app devel­op­ment allows for more uni­ver­sal sup­port of both CSS3 and HTML5.

Ray warned to be care­ful when using gra­di­ents, cus­tom fonts, trans­for­ma­tions, and ani­ma­tions. Browser sup­port for these ele­ments can be dicey and rely­ing on any of them for mis­sion crit­i­cal fea­tures isn’t a great idea.

One of the cool things with CSS3 is the media queries that allow for respon­sively designed sites. Ethan Marcotte also wrote a stel­lar arti­cle at A List Apart on media queries in May of last year.

Before adding new ele­ments from HTML5 or CSS3 Ray cau­tions to look at your tar­get plat­forms. Analyzing your site met­rics will give you a bet­ter idea of what browsers your users are on. This helps you deter­mine where to add enhance­ments and how vital it is to pro­vide alter­na­tive versions.

To add sup­port for seman­tic selec­tors in Internet Explorer and other browsers that don’t natively sup­port them Ray sug­gested using html5shim or Modernizr.

Ray rec­om­mended Browser Labs from Adobe to test sites in mul­ti­ple browsers side-by-side. It’s free right now but will even­tu­ally be a paid tool.

Using cache man­i­fests and .htac­cess rules you can eas­ily set up offline stor­age of files on devices. These pro­vide a great way to store images and other data for use in offline or air­plane modes.