Show HN: I made a free documentation tool | Hacker News Reader

Show HN: I made a free documentation tool

sidepage.co

77 pointsjakeprins34 comments

A few days ago I needed to start writing docs for one of my projects and I went with plain HTML on Tailwind CSS.

Your project looks useful! There are a few things to smoothen out, but these are small cosmetical things like:

- when creating a project and missing a field, button continues to say "Loading..." (should probably revert to Submit/Save)

- success message went behind my avatar top right corner (z-index)

I think one of the important features would be maybe to offer html export, so you can use it as a tool to generate docs, but then you can have the html and update/host on your own.

PS. Tailwind is getting more and more popular. I see a lot of sites where you just instantly know it's Tailwind. I would recommend changing a design a bit to be more unique (like removing these Tailwind dots behind the hero).

I also love utility-first CSS and I just recently started working on my own UI component library as I rewrite my projects on Tailwind: https://appingkit.com/

Edit: ugh, I always forgot adding double line breaks to lists

Thanks for the feedback! I really appreciate it. I like the idea of adding a feature to export it as HTML. I will dive into that.

Appingkit looks nice btw! I will keep an eye on it.

I've tried a lot of similar solutions and I definitely feel like there's a lot of room for something like this. I have been trying VuePress recently and this seems prettier and snappier.

For me to use it I would probably need most of:

* more polish. The next/previous buttons didn't work for me (mobile Brave) and the first time I loaded it I saw a flash of "project not found" or similar before the content loaded in.

* Syntax highlighting

* Examples of what screenshots look like

* Open source with good deployment docs

Hope you keep at it! From what I've seen the biggest killer of projects like this is that the creator gets bored with them. I'm on a mission in 2021 to find or build the perfect docs experience (for Ritza [0]) and this looks like it could have the potential to be close.

[0] https://ritza.co

Thanks for the feedback!

>> From what I've seen the biggest killer of projects like this is that the creator gets bored with them.

Yes, exactly! I think you need to have a sincere interest in your product to keep working on it. At least this is what I feel about my own projects.

If I do something that has a (hidden, often even to myself) motivation to make money or promote my other products, I tend to quickly abandon it. On the other hand if I work on something that I like, I keep doing it for years without making any money at all.

I run a small site that lists projects made by indie devs who share their revenue and I see that the ones who succeed have been working on their products often for years. And they like their products. It's interesting for them. Otherwise they couldn't have done this for a long periods of time without a big revenue. This big revenue usually comes later. And you can feel it from the product too if the maker has put their soul into it.

Seems promising. I will probably try it soon. In the About section, I was not sure what flag this was, it would be nice to give the name of the country. (I guess it would also help with search engines for people looking for this phrase)

Flag is from The Netherlands.

Looks really great. What I didn‘t get from the website

- How are the docs published (private / public address)? Using SSL? - Can I deploy the docs to a custom domain?

Indeed looks really nice and pretty.

Some more questions/suggestions:

- Front page says it's free, no mention of the pricing plans that only show after you login.

- I'd suggest mentioning all the features you support in the main page. ie there is no mention of custom domains.

- Some basic usage metrics would be nice.

- A way to export/import content would be nice.

ps. I created a project with www as the slug (www.sidepage.co) and since chrome is hiding the www it's even worse. Please feel free to delete the project and restrict the use of the www slug.

One more thing, just saw an email that I assume is from this project.

I'd suggest changing this to something more legit-looking.

> Subject: Verify your email for project-10176354815xx

> From: noreply@dope-docs.firebaseapp.com

> Hello,

> Follow this link to verify your email address.

> https://dope-docs.firebaseapp.com/__/auth/action?mode=verify......

> If you didn’t ask to verify this address, you can ignore this email.

> Thanks,

> Your project-10176354815xx team

Thanks for that feedback!

I'm trying to validate the project first, so it's lacking some features. Your suggestions sound like some very good improvements that I will look into asap.

At this point, it's completely free. The paid plans are just dummy buttons. But if people like to project I might at a paid plan later, and limit free plans to a single project for example.

Didn't think of anybody creating a project called "www", haha. I will remove it and add a validation for that slug ;)

It looks good. I've found good documentation SAAS something that is lacking. I've used ArchBee a bit now and they are pretty good.

Search is your main issue feature-wise. I can't even look at a project without search.

You can use a sub domain black list for things like this, for example:

https://github.com/sandeepshetty/subdomain-blacklist/blob/ma...

Thank! I'm validating if people are actually interested in something like this, so it's still very limited. Your projects are now live as soon as you are creating a project. I think will add a "publish" button soon.

I'm going to look into custom domains! A custom subdomain was my MVP version, but having a custom domain is something people definitely want so hopefully I can add that options soon.

I will also investigate how much work it would be to add a "export to HTML" button.

Awesome, this is really my favorite kind of marketing. I would love it if more marketing dollars went into projects like this instead of generic ads. Great stuff!

Im surprised it’s not open source?

Really like this kind of projects. For me a killer feature would be to just write my docs inside google docs and render the website from that.

That would help a ton with sharing to other people (especially non-tech), gathering feedback as comments, a simply being able to tweak your docs anytime, even from mobile.

Looks interesting, maybe I’ll use it. But the main page would more easily draw me in if it had an example of how it’s used.

Thanks for the feedback. You can find an example at https://serverless-saas.sidepage.co

For me the biggest problem with documentation has been keeping it up to date, aka "Documentation is a future lie". This seems to produce nice looking documentation but puts updating it in a separate workflow from changes in the code. Will it do anything to help people make sure that the contents stay relevant?

Thats a valid point!

I'm actually still validating the MVP version and I have a lot of ideas on how to improve. I'm think about adding a feature to connect your github repo with SidePage and adding a "changelog" feature where you docs on SidePage also show your latest changelog entries. Still need to work this out. Also would be cool if you could just import your poject and generate some pages from the project's readme, but again I haven't worked out the details yet. I will investigate this further to see what options are available to improve the workflow of updating docs.

I love the idea but have given up on Markdown - any chance you can also support AsciiDoc?

What's the benefit AsciiDoc has over Markdown?

It has many features that are added to MarkDown in incompatible ways (e.g. I was frustrated with tables in the various dialects). I know that the MarkDown stance is that you should just embed HTML but I know HTML well so I might as well write the whole document that way. I experimented with reStructured text and AsciiDoc and found the latter better. Combined with PanDoc ... it's amazing.

I should also note that I'm happily using AsciiDoc with Hugo instead of MarkDown so I was hoping it was available here.

Markdown is great for simple pages, but you need a Markdown pre-processor to do more advanced work like including another markdown file. E.g., you want to write a book and each file is a chapter. If you are writing something with code samples you might want the code files separate so you can test they are correct.

I think it's going to stay Markdown

Just looked at my inbox and I really didn't sign up for "Serverless SaaS Demo" ... what's the relation between the two? Confirming my email address seems to have added me to the sales campaign for the wrong product.

It showed the wrong name, sorry for that.

SidePage is bootstrapped with Serverless SaaS, a starter kit I made (https://serverless.page), and I forgot to change the name inside the email template.

Should be fixed now.

The link in my email now goes to a blank page so I suspect that any future sign-ups will indeed route to a different page.

I agree asciidoc is superior to markdown... however, "the worst is better" attitude in our industry will make sure that markdown continuous to thrive.

> "the worst is better" attitude

I think that's a general misunderstanding and that often "simpler is better" should apply (e.g. the Unix philosophy about tools). In this case, I think that parsing either format is equally complex and that MarkDown's complexity is greater than AsciiDocs when considering the lack of compatibility between extended features (e.g. I found subtle rendering differences between Github and Gitlab which were our public and private repos at my last position.

I think the real fallacy here is that it will cost too much to switch. It really only took a couple of days for muscle memory to adapt from Markdown to AsciiDoc and so I'd challenge HN readers to give AsciiDoc a one-week trial.

Looks nice. Is there some way to delete an account again?

Thanks! Sorry, not yet. I'm going to add a delete account feature soon. If you want your account delete right now please email me on jake@raterfox.com.

This looks awesome

Is it possible to self-host?

No, not yet. But I will investigate to see if I could add an export feature.

Reply on news.ycombinator.com