ddri

That's a great example. I remember a lengthy thread about this on memo-list back when I was at Red Hat. Always made me smile.

It's also how we were able to spin out our company and raise VC on something inspired by experience, if not using the same code, as what we worked on internally. Having one of the Red Hat founders as our investor helped, but I just loved this attitude of "go build something awesome and keep in touch".

I hope your transition goes well!

Thanks for the feedback w3clan. I like the approach you're going with tutorials although I struggle with the usability. This is an issue that plagues the developer community and something we faced building PressGang CCMS at Red Hat prior.

We took over 2/3 of Red Hat's global software documentation with our internal "just for us" tool in the first year of prototyping it. But ultimately we needed to learn a lot about the increasing focus on UX. Plus we learned that, surprise to nobody but us, writers just want to write.

You can see this trend with Dropbox acquiring Hackpad. Collaboration with attention to design workflow is very important. The ability for teams to create content easily is of utmost importance. As LEw Platt famously said:

> "If only HP knew what HP knows, we would be three times more productive."

Corilla's "Collections" module is like nothing else, and that's the real power of the product. Once you try it, there's no going back to "notes" or "documents"... and why would you? The ability to create content, and then grab it as a dynamic group as and if needed - plus push it to a private or publish HTML build in literally seconds? You can see why we've grown so fast.

Looping back around - I would caution investing too much time in tutorials without attention to UX and the design experience for the reader. Our buddy Eric over at Read The Docs is the default host for open source docs, where design matters less, and services like Udemy have raised the bar on LMS and tutorial experiences. Those to me are both extremes, and there's more LMS swarming every day.

IMHO the focus is on overall experience of managing information as a team, and I'd encourage others to join us in tackling this. That is, after all, where both the greatest problems and greatest budget are being directed.

Hi all. This is David from the Corilla team here.

Corilla is a collaborative documentation tool for software teams. It solves the problems of a core workflow for writing, managing and publishing software documentation.

We're currently in the process of preparing version two of Corilla, so I thought I'd take some time to get some community feedback.

We do this by offering a hosted Markdown editor, saving to an internal repository of topics that are accessed by a novel "collections" mode. This lets you collect groups of topics in dynamic folders but tag/context/theme (the missing feature from Evernote or Google Docs), and publish as private internal or public HTML exports in seconds.

There's a whole host of workflow enhancements for technical writers, developer advocates, dev docs, etc. One I enjoy most days is the screenshot workflow - just copy and paste an image and Corilla takes care of the back end hustle (this used to be a mammoth task at Red Hat, now just as simple as copypasta directly into the UI and directly into a version controlled repo).

We also recently announced free docs hosting [0], so the full workflow from "as many writers on the same doc as you want" to "published to hosted docs service" in a few clicks. Again - I wish I had this at Red Hat.

The intention isn't to replace static docs or the "docs as code" movement, but to solve the problem we faced at Red Hat in enabling non-technical teams to... just write.

We're in use in over 85 countries now and starting work on a new version based on our incredible community feedback. Would love to hear your thoughts.

[0] https://medium.com/corilla-blog/corilla-hosts-your-documenta...

Interesting to see this posted, as this wasn't particularly widely used even at Red Hat. And the timestamps for revision history show you that it's of a certain era.

What I would recommend is something like the MailChimp style guide: http://styleguide.mailchimp.com/

The upside here is that those teams are small and centralised and obsessive over the tone of their product. The same goes for other SaaS companies like Intercom (Elizabeth is an amazing content strategist). They have to be.

For context, I'm an alumni of the Red Hat content team, which I joined from a corporate background and was frustrated to see the team relied on the IBM Style Guide. I pushed for Red Hat to make a canonical open source style guide, as I researched common patterns across engineering and tech writing that can create disparity in UIs or APIs if one group ends up writing one way, and another the other.

For various reasons this wasn't a feasible project so my team focused on tooling instead (creating the PressGang CCMS internally, and then I took funding from one of the Red Hat founders to launch Corilla, a collaborative publishing tool for technical writers considered "the GitHub for content teams").

This style guide here is at best a reference for the kinds of things you might want to consider if you're building one for open source. In my era this guide was pretty useless though, as the content team voted for a strange hierarchy of style guides going from the IBM, then the CMoS, then the American Heritage dictionary, and then this guide. Or maybe some variation - nobody paid attention and we all just used the IBM and had opinions.

This is why the smaller SaaS companies make the best style guides (and the MailChimp one is not only creative commons so you can use it too, but not stuck in the awful DocBook XML format!).

thisonemademelaughoutloud

Thanks for your feedback, and absolutely. We're in beta now and the HTML output (going to S3) was useful for validation of the workflow. We're working on the output formats and API at present - a lot of our beta users like Corilla as a kind of technical writing IDE, which is very interesting.

If you have any specific output requests/formats, drop me a line anytime.

This is a great question, and one that I love seeing emerge with surprising regularity in our dev community.

A few thoughts below. For context, I was a technical writer at Red Hat before spinning out the content tool I cofounded. I'm the cofounder of Corilla, a publishing tool for technical writers... Corilla is like Github for content teams (http://www.corilla.com).

Peer review

When asking for peer review, you will mostly get people pointing out a few minor things and moving on. Doing in-depth reviews are really hard, so it's just human nature to find a few things to comment on and fulfil that emotional contract.

Building up a small circle of very close collaborators for peer review is very helpful. But it's hard work - for example I'm in Boston this week, and I made sure I did a deep-dive on a new content deck sent over from another founder from our NUMA accelerator alumni in Paris. Pay that ^&$& forward first.

Technical writing versus marketing

A long time ago in a galaxy far, far away, technical writers openly mocked sales and marketing. Then something called "Google" happened, and writers that didn't take the time to appreciate that every page is now page one suddenly found their career prospects shrinking.

Technical writing is a very specific art, but one that is broadening widely. I look at "technical writer" in the same way as "full stack engineer". The oldskool days of learning dry and emotionless technical writing were kind of like an engineer getting down with LAMP. Ditto how IA and HCI has blossomed into UX.

The best technical writers understand the power of their content and how it intersects with the needs of the reader. And some of those readers are making purchasing decisions. So you can either argue about "technical writing has become content marketing", or you can learn as much as possible to improve your ability to write the right content for the right persona at the right time. Right?

Clickbait titles

Personally I hate them and avoid content because of them. Unless I encounter them because of a trusted referral in my network. Or if the body content is enough to drive my user journey towards that content.

Your case will depend on your target demographic. Are they inclined for clickbait titles? Are they mostly referred by trusted sources/social media? Are they driven by google (or, lol, Bing)?

Graphical aids

I worked with a manager once that was proud that they never watched videos and hated graphics. That was a great experience, because much of the universe is the opposite.

I can list off a lot of figures that support the conversion/retention/activation power of these other forms of content, but it's 2016. We don't have to. It's not even a debate anymore.

The challenge is that they ALL work. Most of us grew up reading MAN pages, right? So what? A good technical writer has to and loves to test the content preferences of their users.

I wouldn't suggest you learn Photoshop necessarily. You could use Freelancer/Upwork to get some expertise in. If you want to DIY, get a design buddy (or pay a few bucks on Upwork to get taught) how to use Sketch and Marvel/InVision. The design space is shifting quickly.

Get better at technical writing?

Join the Write The Docs community. Seriously. Eric is probably reading this thread right now (g'day!), and they are just a wonderful global community of diverse technical writers. The WTD conferences are super sweet too.

Hope that helps. Ping me directly anytime, I live in this space and love to help.