Welcome to the new Yesod Site
I work for Suite Solutions, a company that provides professional services for implementing and maintaining XML-based content lifecycles. Services include style sheet development for a multitude of output formats in multiple languages, content conversion, training, consulting, information architecture guidance, custom integration and support. We are working on ways to bridge the gap between user-contributed web systems like wikis and the more traditional documentation systems in order to provide an interactive, structured knowledgebase and allow technical authors to get feedback directly from their reader community.
My company has graciously allowed me to use this system as the basis for a new Yesod documentation site. I believe this new site will make it much easier for me to add content and keep it up-to-date, and lower the barrier to entry for other contributors. This post will give an introduction to the new system.
Topic-based editing
At Suite Solutions, our business is documentation. The vast majority of our clients author in a data format called DITA. There are a number of very cool features about DITA, but for our purposes today the most important is topic-based authoring.
Instead of authoring a book, or a blog post, or a FAQ, you author individual topics. These topics are intended to be concise and cover a single idea. Then, to produce a larger document, you organize these topics together into a map.
Why we need it
I end up writing a large amount of content on Yesod:
- The book
- Blog posts
- Answers to bug reports
- Email responses on question
This results in a lot of duplicated content, which has two problems: wasted effort, and out-of-date content. For example, I wrote a three part tutorial on enumerators not too long ago. I then decided that it should be in the Yesod book. I copied the content over, updated it a bit, and thought I was done. But there were a number of flaws with this:
- Since the blog is written in Markdown, and the book in a special XML format, I had to spend a significant amount of time converting.
- The blog posts were still sitting on the web for some unwitting souls to find and get confused by the outdated information.
With this new documentation system, we instead author topics and combine them into maps. Then, these maps get published: as blog posts, in the book, or on their own. If the topics get updated in one place, the changes propogate everywhere.
Community
We've been trying to encourage more community-contributed documentation to Yesod for a while now. However, there were a few roadblocks to would-be contributors:
- The Wiki is not tightly integrated with the main site.
- To get content into the book, you have to fork the yesoddocs repo on Github and send a pull request.
By turning the main site into a Wiki itself, it should be much easier to contribute. Individual topics on the site can be authored in HTML, Markdown, plain text or DITA. Unlike most wikis, a person's topics are their own. However, a user can mark a topic as "world writeable" to allow others to edit it as well.
The last piece in the puzzle is how to find relevant content. The solution we're using is labels: over time, I'll be creating a hierarchy of different subjects (templates, handlers, REST, who knows). As you create topics, simply apply the appropriate labels. And when someone wants to find some content, they can use the browse feature.
Bye Old Comments
The new site also brings with it changes to the comment system. You now need to be logged in to comment. This may sound like a disadvantage, but at least in my experience it's irritating to have to enter your name every time you make a comment.
But the bigger change under the hood is that comments are topics themselves. (Yes, that means you could in theory comment on a comment.) This fits in very nicely with the philosophy we've been developing here: you could write a comment on the book, and others will be able to find it in a normal search. Or relevant comments could be strung together into a map and published as a blog post.
One downside is that I'm not going to be migrating the existing comments from the book. Just to make it clear, the comments on the book have been possibly the most important feedback in refining its content, and I am very grateful to everyone who has contributed. Please keep it up!
Missing Features
This is a first release, so you should expect bugs. Also, the UI is very unrefined, especially on the settings page. But in addition, there are a number of features we have in mind:
- A built-in issue tracker. There are a few advantages to keeping issues on this site instead
of Github:
- No more confusiong about which project to assign the issue to.
- Searching on the site for information will automatically find open issues.
- If someone writes a detailed bug report and/or response, it will be easy to incorporate that content in other sections of the site (e.g., FAQ, the book).
- More social features, such as upvoting topics, forking topics, etc.
- Discussion pages. In fact, the comment system is basically a discussion system already, it just needs a little UI tweaking to make that apparent.
If you notice any issues, please let me know. I'm very excited about this new site. I believe it will make it much easier to get quality documentation out.