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!
- 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.