Tag: documentation

Zeal + Vim = offline CakePHP (and other) documentation

As any long time Vim user, I’m constantly looking for ways to tweak and improve my text editor configuration, and make me even more efficient.  Today, I came across a very handy addition – Zeal – an offline documentation browser for developers. (Thanks to this blog post, which also mentions Dash as an alternative for those of you on the MacOS.)

With Zeal, you can download a whole lot of documentation sets for pretty much any web development technology out there – programming languages, frameworks, libraries, tools, and more.  And then you can easily integrate Zeal with whatever text editor or IDE you are using.

For Vim, there are, as always, several options.  Some of them are listed here. I personally opted for the Zeavim plugin.  The installation is straight forward and everything works out of the box.  After giving a quick try, I decided to adjust my .vimrc file to use CakePHP framework documentation together with the PHP programming language documentation whenever I’m working with any PHP file.  Here’s what I had to add:

" Zeal offline documentation
let g:zv_file_types = {
       \ 'php': 'cakephp,php',
       \ }

Now, whenever I edit a PHP file and hit “,z” (I use comma as a leader, by the way), Zeal window pops up with the relevant documentation search.

It’s super fast. It works offline, and it’s awesome!

Google Developer Documentation Style Guide

“Google Developer Documentation Style Guide” is a guide for Google developers on how to write the developer documentation.  As someone who have been involved in technical documentation for years now, I find a general lack of such guides from other companies interesting and slightly disturbing.

Kudos to Google for the effort and for sharing with all of us who are trying to improve the technical writing.

A Million Words Published at Work in a Remote Company

Sara Rosso shares some thoughts on what to document and share, after publishing over a 1,000,000 words while working at Automattic.  Here’s the gist of it:

  • If you’re the go-to person for something in your company, consider how much of it is just gatekeeper information you could document properly to help someone else learn/grow from or work on independently.
  • Separate out processes and historical background from your strategic expertise. Processes and backstory are not really ‘what you know.’ It’s much better to be a person someone asks ‘why’ or ‘when’ to do something vs. the logistics of a ‘how.’ How can and should be documented for others to build off of regardless of your involvement. This should free you up to be more involved in the why, the new, and the next of your work.
  • If you’re repeating yourself in private chats or (gasp!) email on a specific topic, document it. That’s also what drove me to create this blog – being able to answer someone’s question with an answer you’ve already carefully crafted for someone else is a great feeling (and a great use of your time)!
  • Will someone want to know why you decided or executed something a specific way later? Share as much background as possible so colleagues are brought up to speed immediately. Share the setup & thought process you went through, where to find more information, and even the facts, ideas, or information you considered but deemed outside of scope for the particular project. My goal is to hopefully never have someone ask “where did this come from?” or “what’s your source?” or “did you consider this?” (when I had) and instead focus on enriching the discussion or challenging my ideas vs. asking me for information I should have provided in the original post.
  • Gather the best, most complete, or authoritative things you’ve authored and submit them as potential onboarding materials for new team members. Challenge them to ask questions and to find something you need to document.
  • If important progress is made, be sure to update your documentation, or retire in favor of something newer or more complete. We do this by linking from old posts to new ones, and all it takes is a quick comment and a link on an old post.

GitHub starts the Open Source Guides

GitHub blog is “Announcing Open Source Guides“:

we’re launching the Open Source Guides, a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to open source.

[…]

Open Source Guides are a series of short, approachable guides to help you participate more effectively in open source, whether it’s:

  • Finding users for your project
  • Making your first contribution
  • Managing large open source communities
  • Improving the workflow of your project

These guides aim to reflect the voice of the community and their years of wisdom and practice. We’ve focused on the topics we’ve heard about most, and curated stories from open source contributors across the web.

I think it’s a great idea and I really like the execution too.  Most of what I know about Open Source comes from years of participation, and from reading old books, manuals and licenses – not something that is easy to share with people who are just getting their feet wet.

GitHub’s Open Source Guides are very simple, concise and specific.  And they cover a variety of subjects, not just the legal or technical side of things, but also communications, support, marketing, etc.