SaaS-ifying your docs seems risky to me. Writing documentation is a big investment and startups tend to come and go ("it's been an incredible journey").

$39/mo is much more than what it costs to self-host Confluence, which for all its flaws at least leaves you in control of your data and is super extensible.

Improve the data portability story and it'd be a lot more attractive.

Additionally the actual docs and demo site are not loading in time from Australia. The `main.{digest}.js` file is reliably giving me a 15s download time (not TTFB, oddly) (http://i.imgur.com/ay6le8H.png), which causes the entire page to be blank. I have like a 300MS RTT to the server. Get a CDN and use it effectively.

> SaaS-ifying your docs seems risky to me.

It strikes me as a really, really bad idea. Besides the obvious lock-in issues, I've found the only hope of keeping documentation uptodate is to either generate it from the code or keep it checked it in git besides the code.

What's really needed are (1) authoring tools that can produce decent documentation (ideally as docbook XML or maybe asciidoc) for checkin and (2) product guys who are willing to write docs for features before or during feature development and (3) translation services that can actually do a decent job between the big three business languages (English, Mandarin, Spanish).

It's frustrating that 1, 2, and 3 are so very hard to find. Many products live or die by their lack of documentation, but there don't be seem any simple solutions here.

I'm happy to hear your feedback @dnomad. I'll be notifying you once we get to these challenges.

Agreed. Had to shutter the docs I had on ReadMe.io when they upped the pricing. Moved to GitBook, then they too upped the pricing. Now I just keep my private docs locally and in a private S3 bucket. Harder for less tech-savy people to edit them, but it's basically free.

I get that these companies need to make money, but $35-40/month is a tough sell for personal projects and the like. I happily pay for GitHub at $7 or $12/month and I wish one of these many companies would offer that pricing tier for docs.

Hey Nathan! We've never raised our prices at ReadMe for existing customers. I think you might be misremembering :)

That being said, the value of having up-to-date docs that anyone can edit is invaluable. Docs are more than just reference guides!

This looks pretty different to me? http://web.archive.org/web/20160530181746/https://readme.io/...

Haha whoops, I mean we never raised prices on existing customers. But even then, those new prices are just from the past week!

Agree. $40/mo is a bit steep for just documentation and also when VuePress exists for... free.

Hey @regecks, While confluence is extensible, what DeveloperHub.io provides is quite different from confluence offering. DeveloperHub.io is about unifying the experience for both technical writers and developers, while providing you top-notch support and user experience. Extensibility is inevitable, and we are working on integrations one by one as requested by our customers.

At the moment, we provide data portability on e-mail request, but very soon we'll provide you the tools to export and to handle your documentation outside of our website, and to import it back.

We are aware of the longer loading times in Australia due to having our servers in the Ireland. We will be launching soon our CDN to provide faster site speed. Sorry about that!

Keep updated!

Hey again, A CDN and compression is now activated. We achieved 2.3x faster application and only 300ms difference between first meaningful paint in London and in Hong Kong. Can you please give it another try now ;)

The empty page dummy text rectangles are extremely annoying. There's no reason pure text needs a spinner.

Hey @pbreit, The outline exists to show the user where can they edit, we've tried previously without it and users were confused! The rectangles surely do not show on the live pages nonetheless.

First of all this looks pretty nice. I'm a docs nerd and as a whole I like this.

However ... It's slow. Docs should be static HTML. I should not ever wait for text content. If you want to async load some images or embeds that's fine, but I was waiting for the title to load!

As an aside I recently had a nice experience making a static docs site using Nuxt and Vue. Nice combination of dynamic development and fast performance in production.

I agree, this should have been HTML, not chasing the latest JavaScript fad. They managed to get links wrong. How on earth can you get something so easy and fundamental wrong!? I hold down command and click all the time to open in a new tab. They've got it opening in a new tab and following the link, so you can't stay in one place and open several tabs. This is something a beginner with an hour's experience of HTML can get right.

> This is something a beginner with an hour's experience of HTML can get right.

Not to mention it won't take them 2.5 MB, 56 requests, and over three seconds to do it.

Hey @JimDabell, We just launched the internal links feature yesterday in beta mode to test how the users use it! It is still not announced to the users. Your feedback is amazing and we will be looking to enhance it ;) Cheers, Z

And it's fixed now!

Thanks, I can verify that's fixed. The larger point still stands though – testing this, it took 29.74s to load. DOMContentLoaded 19.79s / Load 21.13s. Your main.….js alone took 16.31s. A static HTML page would have taken a fraction of the time and it would be easier to get the basics right. Using an SPA for documentation seems completely wrong.

Hey again, A CDN and compression is now activated. We achieved 2.3x faster application and only 300ms difference between first meaningful paint in London and in Hong Kong. Can you please give it another try now ;)

Hey @JimDabell, can you tell me where are you based?

From their profile: Based in Brighton & Hove, U.K.

I agree with this in principle, except that a good docs library should also have nice full text searching capability. I've yet to see a FT search capability that works nicely with a static doc site.

Exactly! Static documentation has a limit of where it can go. It simply does not scale for big projects.

I find that the best way to build docs is to use some sort of a static html generator and host the html yourself, which is not at all hard to do. There are free and open source themes available to host your own docs in various site generators.

My personal favorite is hugo. Previously I have built a documentation for a large project [0] using hugo and it gave us 100% control over how we design or host it. Outsourcing a doc to a SaaS seems like something I would never do if I cared about the product/software.

[0] - https://docs.dgraph.io

> Outsourcing a doc to a SaaS seems like something I would never do if I cared about the product/software.

I'm inclined to agree, however I could see the argument for it if you are printing money (so even something expensive like readme.io [no affiliation] is inconsequential) and you've got something in place to keep everything up to date, and the docs are well integrated to your new engineering hire onboarding.

@stockkid hey! This works great for small dev teams, but once you get technical writers around and the team gets bigger, static documentation just doesn't cut it and is unable to scale with the demand. Hugo is amazing, but this is the same thing with buying your own hardware and racks, or hosting with Amazon. It's all about the managed service and peace of mind! Thanks, Z

> once you get technical writers around and the team gets bigger, static documentation just doesn't cut it and is unable to scale

I feel that this is not convincing because docs for large software projects are also built using static site generators and git (e.g. docker).

In my case, we had many devs including a full-time technical writer contributing to the doc using Hugo and GitHub pull request and had no problems. I am curious what you think the bottlenecks of static documentation are.

Congrats on launching!

I regularly spend time on developer documentation (just yesterday roughly two hours...). Unfortunately, your messaging does not resonate with me at all.

Creating (good) documentation will never be easy, or hassle-free. We have to communicate/teach technical concepts to a wide range of developers, from beginners to experts, from native-speakers to I-barely-understand-english. Having a huge document with lot's of details is bad, because one can't grasp the big picture. Not documenting all details is also bad. Having multiple documents per topic (e.g. a Getting Started/Tutorial and a full reference) is a hassle to maintain.

I believe Documentation Review is at least as important as Code Review. What you think you're communicating, and what others are understanding, may be very different. Having at least one other pair of eyes look over it is extremely helpful. It is also helpful to maintain a consistent writing style if several developers contribute to the documentation.

Some things that may make my life easier:

- Help me keeping my writing style consistent (e.g. "In this case, foo should be used" and "In this case, you should use bar" are not consistent)

- Help me keeping my text easy to understand (like http://hemingwayapp.com)

- Help me keeping multiple documents in sync (e.g. "You've changed foo_bar to fooBar in reference.md, you should also look at tutorial.md lines 25 and 34")

- Help with the workflow coordinating multiple reviews (we're actually using Github PRs, and I don't see much room for improvement)

Hey @cnj, Thanks a lot for your kind words. There are two steps for having your documentation online: 1- Creating the documentation service. 2- Maintaining the content.

We provide you #1 on a golden plate, saving you many hours per year of designing, coding, maintaining servers and working on integrations.

For #2, we are still getting started. We have been working with tens of technical writers in small, medium and large enterprises and we understand the problems that exist throughout this step. Look out for some amazing features that are coming soon.

When I started ReadMe, I tried to buy the domain developerhub.io to use as name... I was inspired by StatusPage.io. But alas, I couldn't get it and went with ReadMe.io instead :)

What do you see as the main differentiators of DH compared to ReadMe?

(Zaid, feel free to contact me! My email is in my profile)

Oh hey, I recognise your name :)

I just want to say thanks for your efforts on swagger-inline!

I was actually looking for a tool just like it earlier this year. The project I was using it with was in Python so unfortunately we couldn't justify adding a dependency on Node just for one tool.

It did inspire me to write my own similar tool from scratch, compatible with OAS 3.0. Unfortunately it's not open source just yet but I've got most of the sign off I need so hopefully I can release it into the wild sometime.

In our particular use case, we have a series of microservices that inherit from a shared codebase (controllers etc). Funnily enough, I ran into trouble trying to document controller routes bceause... there were none! They were all inherited, haha.

Anyway, I'm impressed that you're still across a number of repos! Maybe Readme is a bit smaller than I figure assumed?

Awesome! I love the idea of keeping the docs right in the code :)

Here's the parent project: http://openap.is/

I don't write code much anymore, but when I do it tends to be non-production stuff like this. (We're a 11-person company!)

Hey Gregory, I believe I was lucky to have this domain! Let's just hope that IO TLD will not be hacked again sometime ;) (https://www.theregister.co.uk/2017/07/10/io_hijacking_in_tra...)

I am quite unsure which one is harder for SEO though, ReadMe or DeveloperHub hah.

Our differentiator: We are all about user experience and the customers. Our typical response time to support requests is 3 minutes. Bugs are resolved in one day, and feature requests are evaluated in less than a week.

I'll give you an e-mail soon!

Surprised nobody mentioned Slate yet: (probably) not as powerful, but free, open source, self-hosted and fully within your control.

https://github.com/lord/slate

What would be the main differentiator of DeveloperHub vs something like Slate or Hugo? I can't figure it out from the DH website copy.

Hey Radim, That would be scalability, extensibility and piece of mind. Our unified editor allows technical writers to use keyboard shortcuts or a toolbar to format text, whereas developers can use Markdown. Slate is amazing, but when you project has 30+ pages, keeping up with links and relations gets hard. Plus does Slate have search with average latency of 2ms? ;)

Finally, it is a fully managed service which will save you many hours of development and maintaining. $39/month is less than what a Silicon Valley engineer is paid in an hour!

Cheers, Z.

What about using a static site generator and a theme oriented towards docs?

That's what a lot of big sites do, for example Docker's entire documentation[0] is driven by Jekyll[1].

[0]: https://docs.docker.com/install/overview/ [1]: https://github.com/docker/docker.github.io

There is definitely room for competition in this space. We use Readme.io and find the pricing a little ridiculous. $100\month for the lowest tier plan. How complex is this product really?

Also, one minor thing that really gets to me is they get to watermark all of your docs with their logo. Like that $100\month is doing you a big favor so you have to pay them back with free advertising.

@ryanackley, Welcome to DeveloperHub.io! :D

Seems cool. I'm browsing your own doc and found one thing i hate tho. Could you please please let user himself decide, if he wants to open next pages(your "Next to read") in new browser tab or in the same one? I hate how every second website doesn't respect this.

Hey @masa331, This is a feature that we just added yesterday as a beta, we will be iterating over according to your request ;) Look out for the changes in What's New (https://docs.developerhub.io/v1.0/support-center/what-s-new) Cheers, Z.

And it's now fixed!

I see all these great recommendations for static site generators here for documentation! Does anyone have a recommendation for something thats geared more towards mechanical? Essentially I need to be able to show an image and the instructions next to it.

We do have multiple customers using our platform for writing device manuals and such! Maybe give it a try and it can work out for you? Regardless, we will be providing features column later on which will allow you to show an image with text next to it! Cheers, Z.

Awesome timing, I need this exact thing right now. wiki on GituHub was driving me mad

ah nevermind too much monies

https://readthedocs.org/ ?

$39 a month for beautiful documentation, and once they finish API with Swagger support it is great value. I can see for open source projects that don't generate revenue the price being expensive, but as a SaaS business owner the pricing feels just right.

You know, I think normally the common sense buy-vs-build wisdom would win out here, but this is truly an offering that is trivial to build out and is aimed towards an audience that can forgive the common UX perils of home built solutions.

Not to mention there are great off the shelf open source alternatives that work FANTASTIC and have most of the offerings listed on this SaaS product. I use https://github.com/Rebilly/generator-openapi-repo which took literally minutes to setup.

Here's my workflow:

* I type "npm start" in my docs project repo and load the tab that contains the syntax-highlighting enabled editor window in the browser.

* I modify my swagger.yml to update my documentation in the editor

* I use the dev preview tab (a separate node web dev server on another port) to see how the documentation looks

* Once I'm satisfied, I commit and push everything into the git backed repo.

My api docs exist on a github page so I don't even need to worry about hosting. As soon as I push my changes, they are live on my docs site. I've setup a CNAME record to point apidocs.mycompany.com to the github page and presto, I have a whitelabeled documentation site that I can update on a dime, for free, with absolutely zero monthly charge.

I have a hard time understanding how even the most elementary of developer couldn't manage to do this. I can't imagine it takes more than two hours for a mediocre web developer to get running (at most).

At what point do you have the financial responsibility to reasonably consider implementing an elementary task yourself instead of SaaSifying yet another area of your company? $49/mo is less than my hourly rate, in theory, but doing it once means one less SaaS bill at the end of the month.

In what use case is buying this product justifiable?

Would need to see your docs before making a comment.

Thanks nodesocket, I love you!

How do people find the balance between Agile (working software over documentation) vs enough documentation that you don't have to ask around your team every time you need a config change?

auto generated swagger docs. They get generated from the swag specs, auto deploy through CI tooling. its now just part of the developers job, as they spec with swagger, docs come for free

Please contact us on [email protected] if you'd like to work closely with us on implementing this. We'd love to get your input in this.

We will be tackling that soon @icc97 ;)

I used this recently and am pleased with the result:

https://github.com/Mermade/widdershins

Congratulation on launching! I built DocsApp to solve similar pain point. For documentation hub, performance is a feature :). Feel free to contact me (email in my profile) to chat.

Thanks! Congrats to you as well! Will do very soon!

Announcement page looks weird in w3m and docs won't render at all. Readthedocs works fine by comparison. I must not be the target market.

Hey @sevensor, I'm not sure which announcement page are you talking about?

For the startup plan and using a custom domain, is it possible to enable https (let's encrypt)?

I wonder how this compares to docs written in VuePress? (https://vuepress.vuejs.org/guide/)

Hey again, this will be available this month! Keep an eye on us.

Is it possible to re-use parts of documentation across different pages?

We have this feature to be implemented in the near future!

Looks great, but VuePress is just so simple.

I literslly just launched our startups product documentation site with VuePress and had a great experience. - host the git repo on github - use github pages to manage the web hosting, it even gives you SSL for free - VuePress generate beautiful docs too and has a super low learning curve.

The one issue with the above setup is that it’s just too techy for the average person. I was looking for freelancers to hire to help me buildout the documentation, annotated images etc. The average writer is far more used to WYSIWYG editors like Word and would have no idea how to use Git. If this solution allows non tech users to collaborate on the documentation, they may be on to something.

my2c. Docusaurus is another great choice!

https://docusaurus.io/