Corilla — Collaborative documentation for software teams

@kunalslab I feel you! Although in itself, multiple tools across an organisation aren't a bad thing, it becomes a mask for enormous opportunity cost when the marketing team, the support team, the sales team and the technical writers are all authoring their own content in their own workflows. This is something we think a lot about, and it's a trend we're already seeing inside of Corilla. Our technical writing community started as beta users, became advocates in their organisation, got their developers hooked on the ease of collaborative Markdown in the same version controlled environment as the writers, and then... the marketing teams took notice. Most of us on the dev side of things have used some form of VCS for years (e.g. I still have "svn up, svn st, svn up, svn st" PTSD!), but making designers and marketers use GitHub is noble in its intentions, but it's not the kind of intuitive workflow that actually inspires highly active use. So we weren't too surprised when we saw beta users from non-technical marketing teams using Corilla as a "staging ground" for their "approved" design and marketing assets. We made VCS easy. The challenge is how we, as you rightly point out, enable the conversation around them. I have a personal interest in a Slack bot for Corilla (@nathan404 isn't a fan 😭) that would at least lower a few more barriers between dominant communication patterns and the exposure/engagement of content in the repo. But beyond that we're open to ideas. Let's say we make the content discovery super effective (and I can sense our friends from Algolia reading this right now!), and nail the user privs (in a way that Confluence really hasn't)... what would help facilitate the conversation around that content?

@davedri that would certainly help. Some way to discover and follow relevant types of content + conversation would be my Holy Grail. Privacy could be just as simple as internal vs. external for now. I jumped to a Slack integration as a solution in my head at first too. Curious—why does @nathan404 think that's not a good idea?

@kunalslab I think it's because @nathan404 doesn't like me having fun 😤 That and how we run our engineering and product pipelines. We all come from an enterprise background, but have all worked in or founded startups. Which means we've seen the damage a rogue CEO can have on jamming features in or demanding engineering ships whatever is shiny that week. At the moment we've got some major updates to the documentation portal, our import and export API, editorial tooling, team reporting and advanced analysis, etc. The Slack bot is in our Kanban's Triage column, but it doesn't make it through the weekly stack rank when we negotiate in the Backlog. As a company we're super transparent with our users both how we work and what we're working on. And I can say I've just not being able to justify the Slackbot as a focus just yet, but I'm tempted to do a little weekend hackathon personally and it would make sense to open source it (with Corilla as just one of the API options). If that sounds interesting to anyone reading, I'd be happy to make a little bounty or work on it collaboratively (again, that Red Hat and community DNA is at our core).

Thanks @kunalslab. @davedri covered it pretty well but I just wanted to my thoughts as well. For me it really comes down to focus, and I believe for small teams that focus is incredibly important. We have lots of really fun and interesting ideas (some even a little bit crazy 😉) in the pipeline and the hardest bit is working out what we should focus on. It's not that I'm against the idea of Slack integration (or other integrations), but that there are other core features that we need to focus on for the time being. We spend a lot of time in Slack and I must admit there are times that I wish we had Slack integration (don't tell David I just admitted that).

Hi @davedri, does it have API documentation? does it support importing from other resources (like github pages)?

@orask In terms of API documentation, we have this on the roadmap but feel that there's some great products in that space at the moment. We wanted to focus first on where the greatest pain was present for technical writers and developers (e.g. all of us) and not replicate what other great companies are doing. It's interesting to note that the various documentation startups tend to get on really well. After all, we care about the same things. Corilla's focus on APIs is a little different to those that emerged as a result of the inspiration of Stripe (and Slate), but that's a way off. As for the importing workflow, that's on the roadmap and something we're adding very soon. I've created a public roadmap entry for this: https://trello.com/c/iNEOB4Q7/21...

@davedri Thank you. I agree there are lots of good API docs but here comes the other issue that we (technical developers) suffer from which is documentation all over the place. Great to see your public roadmap, all the best!

@orask that's a good point. One of the things we like about Corilla as devs and writers is that it bundles the workflow together. Being able to write a topic as a team, collect them into collections, compare version control, and publish to a range of outputs... that alone in one tool would have seemed like the holy grail back in my early techcomms days! Makes me smile to have it all in Corilla now. I hope we can make you smile when we ship our take on the API... 😃 In the meantime please keep those great ideas coming!

A quick video update from downunder: https://www.bonjoro.com/g/tuKd8_...

@stringstory Great question. The kind of technical writing that inspired Corilla originally was the kind we were doing at Red Hat. When I joined we were still hand-coding DocBook XML, compiling with Publican and shipping RPMs. It's the kind of thing some corporations are still doing to create these monolithic narrative "books" for customer documentation. It's slow, expensive and nobody really cares about the customer experience. We built the PressGang CCMS at Red Hat to solve those workflow problems, and over the next few years of speaking about this at technical writing conferences I kept hearing a lot of "me too" from other agitated content teams. But then not just the enterprise teams - we started to hear this from the dev community, and we realised how common this problem has become. It struck me as wasteful that we were all standing up our own solutions - grab an editor, some version control, user accounts, etc. The cost of maintenance is incredible when you think of the dev time going into it. But that's the easy part. The shifting trends of documentation mean it's just not enough to dump a "user manual" with each major release. Teams need to be able to write modular content quickly, with realtime collaboration across the organisation. Then they need to be able to access the existing content through a common and version controlled repository, and finally have the ability to push this to all the multiple outputs that the company requires. One of the areas I think technical writing has failed to deliver is in the "M" part of CMS. At the moment it basically doesn't exist. A wiki is where good content goes to die. It's a nightmare to maintain, as I learned at Red Hat when I took over the MRG Grid docs suite - a product used by the CERN project at the time. Maintaining that was intense, and working closely with our beta community on maintenance automation we've heard how common this issue is. Early days, definitely something we're working on with the wider community - and not just technical writers but the developer community building and maintaining this infra as well.

@davedri Thanks for sharing a deep dive with us. I beginning to understand why documentation is key to the success of a business, especially for scale.

@sarahleeyoga Firstly I should say I'm a big fan of your work in the customer support world, and great to see some familiar faces from the Write The Docs community. It's been interesting seeing how the various "help desk" and "customer support" companies have expanded. Likewise the "customer support. Some like ZenDesk have really high quality documentation portals (we actually used it on OpenShift at Red Hat for a while!). It's a logical move for those companies to host static documentation as customer support without docs is like bailing water out of a leaking boat. This was one of the really interesting things to observe during the beta period. There was a specific demographic of users with subscriptions to these kinds of services were still heavily invested in Corilla. One of the "a-ha" moments for me was hearing one of them describe their view of Corilla as "an IDE for documentation". And the RFEs for integrations came soon after. This highlights that the "missing M in CMS" is an issue not just for companies with a primary focus on documentation, but those with heavy customer support traffic (and as a result - customer support costs). By focusing on the workflow for authoring and maintaining this kind of content, we do our part in reducing that cost of support, and in turn it adds value for us to integrate with the major support platforms.

@chrischinch Thanks Chris. You raise a good point too. The goal for collaboration shouldn't be to convert everyone to the cloud, but to empower those using their preferred tools to align with the kinds of cloud-based experiences being developed. There's a lot of things I prefer on my local system, and we certainly learned this the hard way at Red Hat when we built PressGang originally. Got a dose of what Ed Catmull's writes about in Creativity Inc... that your shiny innovation is often someone else's annoyance. Especially where someone has invested a great deal of time and expertise in developing their workflow. It's a powerful lesson and one I hope we can accomodate as Corilla keeps growing, and as more and more teams (we're over 1000 now) embrace the platform as part of their daily content management experience. TL;DR... no pressure 😬

And here's a quick update: Thanks to Product Hunt feedback, we're building a new version of our documentation portal and knowledge base. And doing it... in the open. https://medium.com/corilla-blog/...

Thanks @christopher_87. We've actually thrown around some ideas in the past on how we could help people improve their writing and it's an area that we're keen to explore. Aside from basic spelling and grammar checking, what do you think would help you write better?

@nathan404 i am not really sure. I have been using grammarly which has helped a lot. Especially with the paid plan.

@xyz_paul that's very kind of you Paul! And congrats on the move to @Canva! Looks like an excellent Aussie startup to be working with.

@masone thanks for checking out Corilla. There's a lot of interesting discussion about how best to address the topic of content lifecycle, particularly in how it ages. In my experience the answer is usually "poorly", and most enterprise teams bike-shed around the issue as maintenance is poorly understood in terms of the economics. I've tackled this on a few projects. The concept of "what you measure matters" applies here, so even if there's natural or cultural blockers against improving your company docs, you can gain some momentum simply by auditing what's out there. And then running analytics on what content is being consumed. And then bonus points for tracking user journeys, and a special prize if you correlate bounce rates against (the count and cost of) customer support. Having said that, you can probably guess what our roadmap looks like here 😎. The long view is in automation of the techniques and skills that people like us develop in our careers. I spoke at a technical writing meetup recently about the machine learning experiments we've been doing to basically put the "M" into "CMS". We can talk off-list if that's interesting to you. As for images, isn't it frustrating how bad the asset management is in the typical "CMS"? In terms of asset management we've got coverage of that at the moment, but the source file question is another thing entirely. Would love to have a wider conversation about that in the community (as there's the whole filesystem versus repo approach here).

@mleonard That's a great question and one that we thought about carefully before we... quit our jobs and went full-time! 😱 Initially we worried about Adobe taking a renewed interest in the plight of the humans it sells technical writing products to, and then we were concerned about the mid-tier companies like Madcap (who are great) and every startup with "content" or "docs" in their marketing. But then we just kept talking to our early users and realised nothing much had changed from when we were forced to build our own solution at Red Hat. I'd actually say that the biggest competition for us is our own community desire to spin up documentation tools 😂. It's easy to stand up a static generator, patch in a VCS and embrace the idea of docs as code. But this is a false economy. Even maintaining this kind of setup for a few hours a month is many times more expensive than the economy of scale that we can achieve as specialists... which is the blessing of the SaaS model.

@eonpilot thanks for the kind words Eon. Coming from an open source culture we find it's best to be as transparent and authentic (and thorough) as possible. We're building for the long-term so anything we can learn and adjust now helps achieve the best product for our users - plus honestly it's just a much better lifestyle. We love this community :)

@evivekpal Thanks for the kinds words Vivek. Let me know how you get on with the trial, or if you would like to run through a demo some time I can show you the workflow and we can talk about what best fits your projects. I always sneak in a few things I find really exciting too 😉

@rueter It's amazing how 💯 this is. We were concerned initially that we were investing our time and energy in building a "technical writing" product in an era of declining techcomms budgets. But we saw almost immediately in our alpha release that documentation is a real challenge to create and manage. And as you say, it there's not docs... there's no product. I wrote something about this recently: https://medium.com/corilla-blog/...

@joshharcus Thanks Josh. It would be great to hear what you think both as a writer and also get some feedback given your experience on the sales and marketing side. As Corilla is just coming out of beta, we're naturally shifting our focus to improve the onboarding experience and reaching out beyond our community. Let me know any time if you would like a demo to run through the workflow and learn more about what you're working on.