from Hacker News

Ask HN: Best tools for creating user and developer documentation for web apps?

by pettycashstash2 on 4/10/24, 6:53 PM with 5 comments

I'm working on multiple web portal projects and am looking for effective tools to create documentation for both end-users and developers. Ideally, it should be easy to navigate, visually clean, and able to communicate workflows, UI, and code samples (see https://docs.craterapp.com/ for a solid example).

What tools have you found work well for building SaaS user guides and technical references that strike a good balance between usability and depth? Bonus if it can output both user and developer-friendly formats. Appreciate any recommendations from the HN community!

  • by koliber on 4/11/24, 9:13 AM

    For internal documentation, I go for a mix of:

    - in-code comments with links to more in-depth resources

    - a documentation directory in some projects and modules that contains markdown

    - a Notion internal wiki maintained by all the developers

    Making documentation easy to navigate, clean to read, and able to communicate depends more on the people writing the documentation than the tool. A plain text file can be great or horrible in those regards. That applies to all other documentation mechanisms as well.

    Companies often don't suffer from a lack of documentation, but from poorly organized, maintained, and curated documentation. The problem is finding what you are looking for. For looking up documentation, the two broad approaches are search and clicking-through-links. Search is broken, and compartmentalized to tools. If you provide proper hyperlinks between different related documents, and organize things into hubs and lists, it should be easier to find docs. I wrote a bit about this some time ago: https://koliber.com/articles/engineering-documentation-best-...

    Also take a look at https://dunnhq.com/posts/2023/documentation-quadrants/ . It will help you wrap your mind around good documentation practices.

  • by noop_joe on 4/11/24, 4:30 PM

    For building docs sites I like Astro. There are at least a few tailwind+docs themes available if you want to get something started fast. By default all content is markdown, but you can integrate with other CMSs.

    I think I used something called Spinal as a reference theme [1]

    I use astro for the development of my company's developer docs [2] -- I would reach for it for internal sites also.

    1. https://spinalcms.com/resources/astro-documentation-theme-wi... 2. https://noop.dev/docs/

    edit: fix link

  • by easyalgocode on 4/10/24, 11:06 PM

    #1 Docusaurus #2 Gitbook

    I would go with #1 all day

  • by austin-cheney on 4/11/24, 8:35 AM

    Markdown

  • by leros on 4/11/24, 7:19 PM

    Docusaurus is great