Thoughts on working together, and supporting organizations

View the Project on GitHub NewAlexandria/leadership_readme

Wiki Patterns

How to wiki

We are Avoiding This

Core Pages

Finding the Home

There is an overall company home, which you should have received an email about when you joined. Keep it handy, as it is generally the root of all other information in the wiki.

Pages for your department, and team

Just like the company having a home, your team in your department will have a single page that is the basis of all related information. It will also include links to important tools, practices, and related resources.

Consider a possible template:

If you notice anything that is important to your work, but it’s not mentioned on your team’s pages, you should feel free to add it to an existing page or a new page anytime. You can confirm where it goes, but proactively adding information trumps losing track of an important thought. Take note of whether a page is a historic record (static) vs. a more-active living document.

Language for Page Types

Make templates

If many of the same pages will be made, make a template. Think about RFCs, client overviews, competitive analyses, product planning charters, etc.

Templates usually capture best-practices around a topic, so it’s good to get people to relate with those structures.

Tech Docs

Remember to include

When to edit the Page, When to Comment

Free free (anytime / future) to make direct additions to the page. I know there can be a tendency to think that someone else is the author or maintainer of a doc – and it feels polite to not change someone else’s work. What scales best, though, is when we all edit docs directly, and develop house-rules in the few occasions that an issue occurs.

Most wiki pages support either inline comments, or footer (‘free’) comments. Durability of the comment commonly drives which to use.

Inline comments often deal with a question, or imperative, that may result in changing the highlighted->commented text.

Many wikis allow the inline comment display to be accompanied by a “Resolve” button. Many comments can be left inline, in a series, like an email thread or text chat. Resolving a comment implies that the discussion resulted in a completed action, and often Resolving hides the comments in the page’s history.

If the text that ‘anchors’ the comment is removed in an edit, usually the comment automatically is hidden.

Inline commenting is key

Footer comments annotate the whole page with an idea. Often these comments allow a threaded discussion. In most cases, the comments do not automatically hide, or have a Resolve concept. As such, footer comments often have long durability.

Special Elements

In Confluence, there are many blocks that can be added for searched content, code formatting, drive files, and many more. You can get an autocomplete list by typing { anywhere in edit mode. Double-click its title bar to re-edit one that you’ve already added.

Common Edits in Hypermedia

Use monospace font for indicating a symbolic concept. Think of a ‘symbol’ as any noun or thing, particularly those having durability across a broad scope in the system.

Replace many of your Slacks

Or emails, if you are a big email person.

Follow the main pages for your teams

The wiki will typically have sections for the whole company, each ‘department,’ and each team. You can Watch, or subscribe, to these pages and get notified when they are edited. Far from being noise, these updates are often significant, and link you to new ‘top level’ things related to your group.

Create email rules for Notifications

Avoid notification overload - use folders. Create an “Updates” folder and create a child within it, “Wiki” or “Team Docs”. When you get email notifications about wiki updates, right-click the email and setup a new rule to organize them into that folder. You may need help from someone that does IT support.

Create slack channels for Notifications

Notifications can go anywhere you focus on the rhythm of the team. If that’s in Slack / etc, then have wiki notifications go there. Use a new channel that’s named for the topic of the wiki page, like an RFC, a team’s bot channel, etc.

Team follows

A wiki admin can add watchers to a page, so a team leader can config these for the team. Easy peazy.