DeveloperHub.io: Create beautiful product documentation, hassle-free
developerhub.io
developerhub.io
$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.
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 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.
That being said, the value of having up-to-date docs that anyone can edit is invaluable. Docs are more than just reference guides!
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!
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.
Not to mention it won't take them 2.5 MB, 56 requests, and over three seconds to do it.
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
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.
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.
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)
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.
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)
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?
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!)
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!
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.
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.
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
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.
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?
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.