Is it possible to re-use parts of documentation across different pages?
DeveloperHub.io: Create beautiful product documentation, hassle-free
31–40 of 70 posts
Re: DeveloperHub.io: Create beautiful product documentation, hassle-free
#32[deleted]
Re: DeveloperHub.io: Create beautiful product documentation, hassle-free
#33First 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 perfo…
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.
Re: DeveloperHub.io: Create beautiful product documentation, hassle-free
#34Surprised nobody mentioned Slate yet: (probably) not as powerful, but free, open source, self-hosted and fully within your control.
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.
Re: DeveloperHub.io: Create beautiful product documentation, hassle-free
#35I used this recently and am pleased with the result:
Re: DeveloperHub.io: Create beautiful product documentation, hassle-free
#36What 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
Re: DeveloperHub.io: Create beautiful product documentation, hassle-free
#37How 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?
Re: DeveloperHub.io: Create beautiful product documentation, hassle-free
#38How 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
Re: DeveloperHub.io: Create beautiful product documentation, hassle-free
#39I 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…
> 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.
Re: DeveloperHub.io: Create beautiful product documentation, hassle-free
#40First 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 perfo…
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 ca…
> 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.