
DeveloperHub.io: Create beautiful product documentation, hassle-free - zeddabaeen
https://developerhub.io
======
regecks
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](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.

~~~
dnomad
> 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.

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

------
habosa
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.

~~~
JimDabell
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.

~~~
zeddabaeen
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

~~~
zeddabaeen
And it's fixed now!

~~~
JimDabell
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.

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

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

------
stockkid
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](https://docs.dgraph.io)

~~~
zeddabaeen
@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

~~~
stockkid
> 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.

------
cnj
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](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)

~~~
zeddabaeen
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.

------
gkoberger
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)

~~~
spondyl
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?

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

Here's the parent project: [http://openap.is/](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!)

------
Radim
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](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.

~~~
zeddabaeen
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.

------
nickjj
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/](https://docs.docker.com/install/overview/)
[1]:
[https://github.com/docker/docker.github.io](https://github.com/docker/docker.github.io)

------
ryanackley
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.

~~~
zeddabaeen
@ryanackley, Welcome to DeveloperHub.io! :D

------
masa331
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.

~~~
zeddabaeen
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](https://docs.developerhub.io/v1.0/support-center/what-s-new)) Cheers, Z.

~~~
zeddabaeen
And it's now fixed!

------
syntaxing
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.

~~~
zeddabaeen
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.

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

~~~
alottafunchata
ah nevermind too much monies

~~~
nodesocket
$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.

~~~
debaserab2
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](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?

~~~
pbreit
Would need to see your docs before making a comment.

------
icc97
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?

~~~
plara
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

------
o_____________o
I used this recently and am pleased with the result:

[https://github.com/Mermade/widdershins](https://github.com/Mermade/widdershins)

------
docsapp_io
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.

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

------
sevensor
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.

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

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

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

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

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

------
lachlantula
Looks great, but VuePress is just so simple.

~~~
shrumm
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.

