101–110 of 111 posts
We are using Docusaurus ( https://docusaurus.io/ ). - it is easy to configure/customise - looks really great out of the box - solid documentation - fast In our case, we just had to change the colors and font. Here is our Docusaurus code if that's helpful: https://github.com/ToolJet/ToolJet/tree/develop/docs and here is the live documentation: https://docs.tooljet.com/
I'm using mkdocs with the material plugins [1]. I'm running it mainly for a Blockchain Education site for my labs from my course, which seems to be fine [2]. I did a fair amount of customization though, so I am running all this as mkdocs plugins, not directly from the materials project. [1] https://squidfunk.github.io/mkdocs-material/ [2] https://ethereum-blockchain-developer.com
We are using Docusaurus ( https://docusaurus.io/ ). - it is easy to configure/customise - looks really great out of the box - solid documentation - fast In our case, we just had to change the colors and font. Here is our Docusaurus code if that's helpful: https://github.com/ToolJet/ToolJet/tree/develop/docs and here is the live documentation: https://docs.tooljet.com/
I am "eating my own dog food" in the sense that I am currently using two projects that I developed specifically for that: - HastyScribe[1] -- an opinionated markdown compiler that supports advanced features for technical writing like macros, fields and transclusion. - HastySite[2] -- a highly customizable static site generator based on HastyScribe and min[3], another project of mine (and a pretty deep rabbit hole to…
Can you link me or explain some more what you mean by macros, fields, and transclusions? Your project makes it easy to document these aspects of a programming language? Or these are features of your documentation system itself?
https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm#Mac...
Basically it's like defining simple functions with parameters.
And here is a section about transclusion, which is a fancy tech writing word to say "include text from another file":
https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm#Tra...
Antora, which uses Asciidoctor (rather than Markdown). The obvious example is the Antora and Asciidoctor documentation: https://docs.antora.org/antora/2.3/ https://docs.asciidoctor.org/asciidoc/latest/
As I read through these comments (and discover some interesting tools!) I want to give a word of caution for anyone using this thread to make a tooling choice. The "best" documentation system for you is heavily dependent on your product [1], your contributors [2], and your ability to maintain/customize the underlying tooling. Just because you're seeing Tool X 10 times in this comment doesn't necessarily mean it's bes…
If your contributors aren't technical then things that require Markdown, Git, or a build process are rejected pretty much immediately.
Currently I'm looking at Mediawiki or WordPress, but I'd love some other suggestions for non-technical contributors.
If you're looking for a SaaS solution, I can really recommend Archbee[0]. We've moved to it from ReadMe[1] recently, due to constraints in ReadMe's product and the challenges scaling it commercially in our model. [0]: https://www.archbee.io/ [1]: https://readme.com/
What ReadMe constraints did you run into? I don't work for them, I'm just a technical writer who has to use it from time to time and wants to be aware of footguns.
As one example, they see a 'project' as one single set of cohesive documentation and they've built a UX/UI to facilitate that. This is perfectly fair but it means you need multiple projects for multiple documentation projects. In simple terms, everything in a project is intended to be 'one thing'.
Again, this might be fine but projects are so distinct and separated that it makes them really hard to maintain at scale (lots of repetition, no setting or customization sharing) and frankly, if you need the full customisation options you need to $400 a month for _each_ project.
This is a pretty unique to our model, so it's not really a criticism of readme, but it's the reason we've left. Archbee has some (not all) of the same limitations, but they don't charge us $400 a month for each project!
Markdown in Git, Gitlab or GitHub. KISS.
I want to pay for the services to be able to export PDF, but their "starting" plan is for $6.40/mo/user AND you are forced to start with at least 5 users. So I would have to pay $384 per year just to be able to export PDF for a single documentation with a single user.