Realbook - declarative provisioning of linux servers

Maybe it’s crazy to reinvent the wheel, but I never really liked the fiddliness (and yaml-ness) (and python-ness) of Ansible, so I built this. I’m currently using this to set up some (metal!) servers in a datacenter.

https://hexdocs.pm/realbook

What was the reasoning behind the choice of the name for the Library? I ask because is not giving any clue about what the Library is doing.

The docs don’t give any concrete examples how to do what the library says it does:

A simple, imperative DSL for remotely provisioning and setting up linux-based servers.

1 Like

I am going to second @Exadra37 here. You should put a very brief how-to at the top of the page…

3 Likes

Oh yeah that’s a good point. This information is in the readme and the guides. I’ll also put it up on the docs first page.

2 Likes

Many people, myself included, click a link and if they don’t see immediately what the thing is about will just mutter “WTF is this?” and leave, likely to never return.

1 Like

Thanks for the input! I figured out how to wrangle hexdocs to get it to display a more comprehensive, introductory example as the index page, so it’s been updated now. Happy to take more criticism on the docs, it’s always tough when you know intuitively “how it’s supposed to work” but others might not.

It’s still not having a working example of using the library, just some wording, and that is not enough to hook visitors, at least the ones like me :wink:

are you seeing the dhcp server example?

EDIT:

use this link, sorry:

https://hexdocs.pm/realbook/

2 Likes

Yes I can see it now, but the link in topic is not showing that. I think the landing page should be clear and contain a working example.

1 Like

Unfortunately I can’t edit the top post in the topic.

You can ask the moderator to fix it for you, but I think you are missing the point…

As it stands now, the landing page of your library is the link you have in the topic, and that landing page doesn’t have nothing that gives me a clue of what the module is capable, as said before, a real world working example.

If you keep it as it is the success of your library will be affected, because the majority of us will do what @dimitarvp told you:

See the Domo library for an example of what we are recommending you to do. Can you see that the code examples start immediately after the introduction, thus catching immediately the developer attention, after all we love code :wink:

1 Like

Hey I think we’re talking past each other. Is the landing page for the library docs not currently “introduction to realbooks”? This page has its “example” which is a complete example of using code to set up a dhcp server right after the preamble. It’s possible I set something up incorrectly in mix settings.

1 Like

Sorry, somehow I missed that the landing page have changed.

You can ask a moderator to update the link in the topic.

Haha whew. I wasn’t 100% sure and I know there are multiple ways in to hexdocs (search, link from hex etc) and I was worried the mix hack didn’t work.

1 Like