[HN Gopher] Show HN: I made a free documentation tool
___________________________________________________________________
Show HN: I made a free documentation tool
Author : jakeprins
Score : 57 points
Date : 2021-01-03 09:25 UTC (13 hours ago)
(HTM) web link (sidepage.co)
(TXT) w3m dump (sidepage.co)
| I_am_tiberius wrote:
| Looks nice. Is there some way to delete an account again?
| mlok wrote:
| 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)
| rapnie wrote:
| Flag is from The Netherlands.
| raunometsa wrote:
| 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
| jakeprins wrote:
| 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.
| swalberg wrote:
| 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?
| surfsvammel wrote:
| 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.
| jakeprins wrote:
| Thanks for the feedback. You can find an example at
| https://serverless-saas.sidepage.co
| chrisandchris wrote:
| 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?
| jakeprins wrote:
| 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.
| geoah wrote:
| 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.
| geoah wrote:
| 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
| jakeprins wrote:
| 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 ;)
| mchusma wrote:
| 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.
| smoyer wrote:
| I love the idea but have given up on Markdown - any chance you
| can also support AsciiDoc?
| jakeprins wrote:
| I think it's going to stay Markdown
| smoyer wrote:
| 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.
| jakeprins wrote:
| 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.
| smoyer wrote:
| 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.
| elviejo wrote:
| I agree asciidoc is superior to markdown... however, "the worst
| is better" attitude in our industry will make sure that
| markdown continuous to thrive.
| smoyer wrote:
| > "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.
| tenaciousDaniel wrote:
| What's the benefit AsciiDoc has over Markdown?
| jkmcf wrote:
| 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.
| smoyer wrote:
| 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.
| sixhobbits wrote:
| 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
| raunometsa wrote:
| >> 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.
| jakeprins wrote:
| Thanks for the feedback!
___________________________________________________________________
(page generated 2021-01-03 23:02 UTC)