This is the home of SmartOS Documentation.

Proposed Outline and Structure of SmartOS Wiki

The SmartOS wiki is an excellent hub for community resources where the community can learn about SmartOS and directly contribute to the SmartOS development effort. However, the wiki can use a helping hand. So, I put together this proposed outline in the hope of imbuing the SmartOS wiki with a logical structure. My goal with this outline is to make the content easier to consume and also make it easier for people to contribute. 

Please take a look and let me know what you think! At some point, I will compile all feedback and share it with the community. You can comment directly on this page or you can send an email directly to me at jason.davis@joyent.com. 

Type of content needed in SmartOS wiki

My general approach is to identify how I can compartmentalize the content into discrete and semantic sections. I don’t know if that approach is appropriate for this content. So, I want to start first by identifying the type of content the community needs based on what we already have.

• Configuration tasks
• Management tasks
• FAQs and additional resources
• Community engagement
• Context and historical relevance
• Issue tracking/change log

Audience Profiles

Here are a few audience profiles that I have identified as the type of people most likely to look for information in this wiki. Once we have a better idea of who is looking for what, we can mold the wiki so that people know how to zero in on the information they need. I'm not sure if the below designations work but they do provide context for how best to structure the wiki. Does this adequately cover all use cases?

• Beginner: Don't know anything about SmartOS and are curious. These people need access to introductory content, links to videos, use cases, historical content, etc.
• Intermediate: Just downloaded the ISO and want to fire up their first VMs. These people need short and sweet quickstart guides.
• Advanced: Want to modify SmartOS and/or recompile it themselves, want to migrate from a different virtualization product, etc.

Proposed outline

Here is my proposed outline. I consider this fluid at the moment. This outline is based on how my brain compartmentalizes stuff and how we currently structure the SmartOS wiki. To my untrained eye, most of what we have in the SmartOS wiki could go into a “tips and tricks” section.  That is probably a misguided view.

So, the challenge here is to figure out how the content we have fits in with the core SmartOS setup/usage experience vs. ancillary tasks/useful tips. This should then lead to a better understanding of current gaps and what we need to do with the wiki going forward.

1. Introduction/Home
   1. Why SmartOS, KVM, DTrace
   2. SmartOS Virtualization
   3. SmartOS changelog. Optionally I can stuff this in the back of the wiki somewhere and just link to it from the Introduction page.
2. Community Engagement
   1. Annoucements
   2. Events
      1. Event suggestions
   3. Historical relevance
      1. Who is who
   4. Wish list or Requests
3. Install it
   1. Download
   2. Getting started
   3. Hardware support
   4. Creating bootable USB key
   5. Guest OSs
4. Use it
   1. How to create a VM
      1. “...a single page (easy to locate) that describes (in copy'n'paste form) how to install your server and get your first vm up'n'running.”
      2. Using VM admn
   2. How create a zone
   3. Managing Datasets
   4. Working with Packages
5. Extend it
   1. How to integrate your stuff with SmartOS
      1. “What I do have (and I'm pretty sure I'm not alone there) is a fair amount of experience from various opensource projects I'd _love_ to see running on SmartOS.“
      2. “...tips about hooks and libraries we may utilize to get an even better ‘out of the box’ experience running under SmartOS.”
   2. Contributing to SmartOS
   3. Building your own packages
   4. Building your own dataset
      1. SmartOS based
      2. VM based
   5. Building SmartOS on SmartOS
   6. Extending SmartOS-live
   7. 3rd Party SmartOS Extensions
6. FAQs
   1. Extra configuration options
   2. How do I take obtain a system crash dump via IPMI?
   3. Questions from SmartOS the Modern OS Webinar
7. Tips and tricks
   1. Tuning the IO throttle
   2. Enlarging a Windows 7 VM disk
   3. Managing NICs
   4. Migrating from ESXi 4.x
   5. Remotely upgrading a USB key based deployment
   6. SmartOS remote management
8. Resources
   1. Consolidate videos here
      1. SmartOS KVM screencast demo
   2. More information and resources

SmartOS Wiki Feedback

Here are some notable comments on the SmartOS wiki and thoughts on improvement. Names and faces have been omitted to protect the innocent.

Topic on how to Integrate "my stuff" with SmartOS

"...there should be a page describing 'How do I integrate my stuff to SmartOS'. I would love to contribute to SmartOS itself, but unfortunately I don't have enough time to sit down to get my head above the water to learn about how all the nice stuff in the kernel works. What I do have (and I'm pretty sure I'm not alone there) is a fair amount of experience from various opensource projects I'd _love_ to see running on SmartOS. It would be great to have some tips about hooks and libraries we may utilize to get an even better "out of the box" experience running under SmartOS."

Too much overlap in current wiki

"One of the biggest issues I have with the wiki is that duplicate information is sometimes spread across multiple pages (in slightly different forms on each) and when someone comes onto IRC it's not always obvious which (if any) wiki page will best answer a question they've asked."

Use of vmadm biggest culprit when it comes to overlap

"The biggest culprit when it comes to overlap is information on use of vmadm to create KVM VMs and SmartMachine zones. If that stuff could be cleaned up and properly consolidated / reorganized, I think that would be a big win."

Perspective on why you don't install SmartOS to disk

"Somewhere in Section 2 (Installation) there probably ought to be some space set aside to discuss why SmartOS works better without actually being installed to disk."

More introduction/perspective on SmartOS features

"Several key features are named over & over when selling SmartOS, but in & around the Illumos community it can be very hard to find good introductory doc on what they are and how to use them: DTrace, Crossbow, etc."

More direction from SmartOS dev heavy-weights

"As part of the Community section, I think it's very important for the well-versed "silverback" devs to take a step back and define a foundation to help bring new contributors in quickly. How to set up a build zone, what's the workflow for keeping up with SCM & getting patches pulled in, how to contribute patches, etc."

Need sections on migration

"There's two sections that weren't mentioned in your outline: "Migrating from Linux KVM" and "Migrating from VirtualBox". I know the former is quite easy, and the latter is possible. I've heard a number of people asking questions about both."

Need to emphasize pkgin

"Another section is pkgin. Zones without pkgin are a hostile place – I've been there, and I'd never do it again. pkgin really deserves emphasizing."

JD: Do you mind sharing some of your pitfalls on working in a zone without pkgin?

"It's a pain in the arse!

Zones exist to do things with. Typically a zone doesn't contain the application code or many of the libraries you want, so they have to come from somewhere.

Here are some alternatives:

a) blastwave - they're trying, but my experience with that stuff was unpleasant
b) sunfreeware - worse than blastwave
c) compile from source - on Linux this'd be easy, but fudging is often required to get things compiling on Solaris-derivatives

Just use pkgin. The End.

Well, not quite. The stuff in pkgsrc isn't thoroughly tested, so often some package or another doesn't work properly. It's important that the community get feedback about these failures so we can fix it for others as well. One alternative is letting us know on #joyent@irc.freenode.net. A second is writing an issue on https://github.com/mamash. The third is probably writing to smartos-discuss email list.

We really need to make this as simple as possible, because without a good package manager SmartOS zones become nigh useless."

Cheatsheets

"I strongly urge a cheatsheet section that quickly summarizes important things. Many of my favourite textbooks take such an approach, leaving the details for later chapters. This section could (and arguably should) serve double purpose: IIRC, some BSD's have a "man firstboot" which serves as a crashdrive into the system, and content from such a section in the wiki could be copied into this manpage too."

JD: Can you elaborate on this a bit more? Do you have an example you could share with me?

"Not offhand, no.

By double-purpose, I think it'd be nice to have all this material in a manpage too. Someone on IRC once mentioned that some BSD's have a manpage for newcomers that summarizes various common commands, filesystem locations, and differences with other unicies. I think we should copy that. If you're writing that material for the wiki anyway, might as well copy it into a man page. 

As an aside, the major problem with most manpages is they don't provide any examples. Examples make life so much easier. Perhaps the cheatsheet should be a table divided in two, one side a common command, the other an example: cheatsheet example.rtf

Nahum: I don't have code I can point to, so this suggestion is only partly useful... If there's something that can parse confluence markup, perhaps a tool could be written that pulls some cheetsheet pages from the wiki and converts them into man pages to be included in SmartOS.

Section on creating your own services

"It just occurred to me that it'd be nice to have a section on the wiki about how to create your own services. This is common for any server application, yet making a service is a somewhat tedious affair that usually involves cargo-culting. There are a number of small apps out there which make the creation of a service manifest much simpler. Beyond packages, I think services are the second most likely thing to scare people off."