I need to create a guide or wiki that outlines different standardized techniques for marking up reusable elements in our software. When adding new features our developers are often able to reuse or mimic existing markup, and I'd like to make this as easy as possible for them. In order to do this now they have to dig through the interface to find something that's close enough.

Are there any good examples online that show code samples for standardized markup?

Is there a tool (wiki, etc.) that would make this somewhat easy to create?


Microsoft Visual Studio has a feature called "code snippets" that allows developers to create and then quickly insert (using a menu or a keyboard shortcut) those snippets inline at the caret while editing. I know it makes my coworkers quite happy because they can write less boilerplate code and focus more on the business logic. Here's what it looks like:

enter image description here

Obviously this example is for Visual Basic, but it exists for HTML and CSS as well, or whatever markup you want (such as XML). You could consider offering a rich control like this so your developers can manage their snippets. Providing documentation alongside each snippet should be trivial.

Alternatively, we opted for something more lightweight in Handcraft. In our tool we ask designers to write HTML prototypes with a few tags added to HTML to make some things possible that aren't with vanilla HTML. We're aware that some people will face a learning curve in order to get into that, though, so each new user is introduced to the new markup with a guide.

The guide consists of a series of steps where we walk you through the new markup and the things you can do with it by following interactive tutorials; we show you a tag and then ask you to do something. It works quite well.

The way we present the guide is by displaying an accordeon control next to the code editor. When you start, the first step is expanded but there's a "next step" button which collapses the first step and expands the second:

enter image description here

If you wanted a less flexible but simpler system than what Visual Studio offers, perhaps you could consider offering your developers control like our accordeon that allows them to quickly see standardised markup (as "snippets") and edit them when necessary? I imagine you'd want to organise by purpose rather than steps in a process.

  • Though I don't much like the snippet manager in VB, it does serve a purpose :-) The +1 is more for your accordeon idea. Pretty nifty and I am thinking of including it in my software application as a getting started guide for new users. I had "welcome" page in mind, but this feels better (less overwhelming at first). – Marjan Venema Aug 14 '11 at 7:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.