Skip to main content

2 posts tagged with "docusaurus"

View All Tags

· 5 min read
Tim Post

The point of an early design partnership period is to match everything your product is capable of doing with what the current market needs it to do in order to achive fit. Right now, early software startups really seem to need turn-key documentation sites that someone else hosts and updates for them, so that's precisely what we're putting into the first product that we've actually developed in conjunction with early clients.

We can now deliver a fully-responsive developer documentation & community site with the following features:

  • Automatically updated by us! We manage content updates, release notes, screen shots, feature spotlights and feeds. You schedule releases on a shared calendar and push a button to make it live when you're ready. We handle updating your documentation and writing the release notes automatically!

  • We can pull tickets that you tag for us in your existing issue tracking software to help us build narratives around releases. Just tag them for-echoreply along with major item or minor item respectively and we'll use them as building blocks in the story. We don't require many face-to-face calls.

  • Built on Docusaurus to bring the flexibility of MDX and fully-responsive / accessible design that is easy to customize to match your brand. We'll handle the initial theme setup to blend with your site. Anyone that knows Markdown can edit content; advanced users can use MDX and react components.

  • We store your video content on IPFS through Filebase. No more cluttering git repositories with mp4 files, or uploading videos to YouTube (unless you want to!). Additionally, Filebase provides true distributed storage via IPFS; while it provides an Amazon compatability layer in the form of an S3 compatable API, your files are actually hosted around the globe and pinned on the real IPFS.

  • Static content is built and Hosted on Netlify with serverless functions enabled for richer content experiences, metrics, live support and others. We're actively developing more Docusaurus plugins that take advantage of serverless functions, which is outside of the realm of the goals of the project itself.

  • Organized so that all of your content is stored separately from code, in plain text files. Anyone with knowledge of Markdown can create, edit and translate content or send pull requests to improve it, but your functions, components, configuration, etc is stored in a private repository. We accomplish this through Git submodule orchestration.

  • We submit PRs in advance of release dates and collaborate around it just like you currently do code, so you always know in advance what's going to be published.

Pricing for this depends on your release cycle, and the complexity of your software. To make sure the product works well for everyone, the base price includes having us involved in all of your releases, even minor ones, so that we remain involved in the release narrative. We'll make a bigger production out of the ones where there's more to get excited about.

If you're interested in this, please reach out to us so we can assess your product and see if we'd be a good fit at this stage. We can support monthly or longer release cycles with very little lead-in time and be up and running smoothly within 45 days.

Does it have to be (Docusaurus / Filebase / Netlify / etc)?

For now, in most cases, yes. Gatsby is another option if Docusaurus won't fit the bill.

This arrangement lets us automate (for the most part) both the incoming end and delivery end of the work. However, it's feasible that we could do things a little differently - reach out to us if you have something else in mind and we'll see how it might fit in our workflow.

Can you migrate our existing documentation site?

In many cases, yes. It would depend on the volume of content, the amount of content with proprietary markup, internationalization strategy and design. We'll apply your logo and brand theme colors when we get started.

How do you coordinate everything?

We use a shared calendar (Google) as well as a shared Slack or Discord channel; for the most part we'll feel like a part time remote employee.

Who writes the content?

The person with the most experience in your domain (who also naturally knows what to look for) will put together the foundation for the content. For consistency, only one or two editors (max) at a time work on the final product that we commit, so that voice and tone stay the same and writing standards remain above objectively met.

How much is it?

The base price is $2500.00 Monthly and includes two feature screencast videos and up to 10 pages of documentation professionally written or updated each month.


A 45 Minute Introductory Call Is Free - Take Advantage Of It With No Obligation! →

The initial evaluation is free and there's no pesky sales follow up calls. If we don't get excited about working togther on the call, we won't pester you.

· 4 min read
Tim Post

We pay marketers to come up with landing pages that resonate with developers, and those marketers ultimately pay the very developers they're hoping to entice to build the page .... doesn't that sound a little bit weird to you?

MDX means better marketing. If you take nothing else away from this, make sure that you look into putting MDX/JSX in the hands of your marketing team, so that they can form and bake their own clay in the kilns. Pages that marketers can produce themselves, with no other gate keepers, are going to convert better and faster than anything else.

Why is this?

  • Because your marketing team can make mistakes faster, learn from them, and iterate in multiple directions at once. You're freed when the prospect of possibly wasting someone else's time is off the table.

  • Because your kickoff meetings will stop ending on downers when people realize that it will be weeks before developers can make pages live for them, or anticipation of developers challenging even the premise of the idea in the absence of data. It just feels 'too uphill.'

  • Because people tend to dumb their ideas down significantly when they know that they'll be relying on other people's time to deal with whatever comes of them. I'll be much bolder in initial copy, for instance, if I know I can walk it back quickly if a hunch doesn't play out.

And there are more and more things that come into play, but none of this is new. We've tried developing CMS systems that are more 'friendly' to 'non tech folks' and other things, but in reality, we just end up abstracting all the wrong things and end up giving them something that feels heavy, ill-suited and constraining.

What if the only bar to being able to put raw ideas on the Internet and see how people react to them was learning Github Flavored Extended Markdown and how to copy / paste / tweak a dozen or so React components where a more interactive experience is needed?

When we set up Docusaurus for any tech company, one of the VERY first things we do is provide them with components to embed conversations on social media, videos, arbitrary JS widgets (discord, twitch, etc) and guidance on how to handle images properly. This means their marketing teams don't need developer help in order to devise their experiments and rock on with them, nor do they need to learn some kind of software - they just need to know how to use a text editor and have a markdown cheat sheet.

While we Love Docusaurus and will be continuing to use and promote it, it's just one of many that you can use. Anything that lets you mix components with markdown naturally, with a styling system that's easily abstracted away means you're giving your marketing AND engineering teams equal footing to throw things at the wall. There's probably more friction here than you realize, unless of course you're a marketer.

Most of my best accomplishments in driving growth share a characteristic with my non-accomplishments: they started off as hunches and intuition I needed to see a bigger sampling of before I could explain them to someone else.

Knowing how uphill that can be, I learned to abandon ideas that required more than a trivial level of emotional investment quickly, or defending even just one could get so emotionally-draining that I'd need an entire day off to want to be around people again. That's a shame, because a bunch of great stuff never happened at Stack Overflow, mostly because I couldn't figure out how to back the idea with enough data to justify any engineering time being spent on it even just to see if it would incubate.

Don't let your company be like that. Free your marketing team so they can be contenders for adults in the room before you decide who the adults are going to be when growth slows and someone has to try something. Remove the clogs from the output side of things first.

MDX is a big step forward in that process and you need to make sure your marketing team has access to a platform that enables it.


A 45 Minute Introductory Call Is Free - Take Advantage Of It With No Obligation! →

The initial evaluation is free and there's no pesky sales follow up calls. If we don't get excited about working togther on the call, we won't pester you.