[HN Gopher] Ask HN: What are you using for public documentation ...
___________________________________________________________________
Ask HN: What are you using for public documentation these days?
On a new side project I'm working on I need to have a fair amount
of documentation for usage, implementation, options, etc. In the
past I've used https://docsify.js.org hosted on Vercel, but I was
curious if there is anything else out there people like. Looking
for free or paid options. So long has I can host on a subdomain I'm
indifferent. Thanks!
Author : vital101
Score : 145 points
Date : 2021-11-18 11:43 UTC (11 hours ago)
| jabo wrote:
| We use Vuepress for Typesense's docs: https://typesense.org/docs/
|
| I like the fact you can plug any vue components into the
| markdown. Haven't started using that feature extensively yet, but
| the fact that it's available is reassuring that I can customize
| things well if needed.
| webwanderings wrote:
| Docusaurus. It is so easy. I only wish I could figure out how to
| integrate xterm.js into it.
| innocentoldguy wrote:
| Asciidoc and Antora. We document a product that has a bunch of
| micro services and each micro service is in a separate git
| repository. We store our documentation alongside the related code
| in git, so it is spread out across several git repositories.
| Antora makes it simple to pull asciidoc files from multiple git
| repositories and compile it all into one static site. It also has
| good search functionality and support for versioning using either
| git branches or tags.
| andix wrote:
| Markdown in Git, Gitlab or GitHub. KISS.
| jonjon10002 wrote:
| Markdown, Gatsby. Source is in GitHub, GHA builds the HTML
| output, then schleps it over to an S3 bucket.
|
| I inherited this setup. Works great from my end, but we've got an
| engineering team that set it up and owns the plumbing of
| everything. That's key, because many orgs have a "we set it up,
| now it runs forever and you deal with it" mentality. And Gatsby
| has a super steep learning curve. And I'm not a designer.
|
| Previously used Jekyll and still use it (minimally) for my blog.
| Jekyll is okay but once you get past a couple hundred pages,
| performance gets exponentially worse. Had a site with a few
| thousand pages, and builds would take an hour or more. And that
| org had the aforementioned problem. A team designed it, then got
| laid off, and I'm trying to read a dummies book to figure out
| what size hammer to hit the thing with.
|
| I've been in this for 25 years, so I've used about everything
| else. Flare, DITA, FrameMaker, RoboHelp, PageMaker. No
| typewriters, thankfully.
| krish888 wrote:
| Stoplight.io
| warpech wrote:
| We (Handsontable) now use VuePress[1] for our docs[2] and we are
| very happy with it. The best feature for us is the ease of
| customization.
|
| Our challenge right now with the docs is to get a fantastic code
| snippet runner there. But that's beyond the scope of your regular
| documentation management tool, I suppose. VuePress will make it
| easy for us to integrate our solution.
|
| [1] https://vuepress.vuejs.org/
|
| [2] https://handsontable.com/docs/
| royjacobs wrote:
| I can vouch for VuePress as well. It's fairly straightforward
| to set up, and extremely easy to deploy. I've used it to not
| only write the docs for my 6502 assembler, MOS[1], but I took
| advantage of the fact that VuePress could generate a very
| simple front page as well.
|
| [1] https://mos.datatra.sh
| kaycebasques wrote:
| 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 best for you!
|
| [1] E.g. documenting an API is very different from documenting a
| GUI product
|
| [2] E.g. on https://web.dev we had a large pool of authors. They
| were all fairly technical but even so we often ran into questions
| about build errors, etc.
| franciscop wrote:
| I have an unfinished side project called Documentation Page:
|
| https://documentation.page/
|
| It's "unfinished" because I'd need to integrate payments and do
| all the accounting on my side (non-trivial as an individual
| living in Japan), but otherwise it's worked pretty well for my
| own projects.
|
| It parses your Github Repo to generate the website. You can
| define your docs as a single readme.md file, a folder called
| "documentation", or custom configuration otherwise. Some examples
| hosted by Documentation Page:
|
| - https://statux.dev/: simple single-page docs and website, menu
| config in
| https://github.com/franciscop/statux/blob/master/documentati....
|
| - https://react-test.dev/: split into multiple pages, you specify
| the folder and it'll automatically merge the markdown files. See
| config https://github.com/franciscop/react-
| test/blob/master/documen...
|
| - https://crossroad.page/: has an landing page, but that is not
| officially supported (yet). See the configs in
| https://github.com/franciscop/crossroad/blob/master/document...
| djrockstar1 wrote:
| The examples look really elegant and polished. I could
| definitely see myself using something like this. It's times
| like these I wish HN had a save comment button.
|
| Also it's pretty funny that a documentation service has
| incomplete documentation.
| https://documentation.page/documentation#how-it-works
| franciscop wrote:
| Thanks! It's unfinished and on-hold for 3rd parties so it
| doesn't have all docs :)
|
| I might retake it at some point next year to officially
| finish/launch it, like the code is basically mostly there.
| ryannevius wrote:
| If you click on the timestamp for the comment, you'll be
| presented with an option to "favorite" the comment.
| krish888 wrote:
| Stoplight.io it has support for git, CI integration
| eysi wrote:
| We use GitBook at Garden (docs.garden.io).
|
| It's zero effort which is important for a small team like ours.
| Allows us to focus on the content as opposed to bikeshedding
| design.
|
| Overall I'm happy with the look and feel of things and the
| support is typically good.
|
| That being said, they recently shipped changes that essentially
| made the docs site impossibly slow for a few days. They've been
| working on fixing that and it's better, but not as snappy as
| before. I also preferred the previous look (it's very similar but
| the new one is a bit more clunky imo).
|
| We do have a lot of long code examples (YAML reference docs)
| which I think may contribute to the "sluggishness".
|
| But overall I'd recommend if you want to minimise effort and
| maintenance. In any case it's easy to give it a spin and see if
| it works for you.
| mooreds wrote:
| We use asciidoctor + jekyll at $CURJOB. It seems to work great,
| can be hosted for free or low cost. Lots of templating wins.
|
| I do wish it supported running code snippets, but I think that
| can be done with some scripts and including things. (On the list,
| not done yet.)
| pydry wrote:
| hugo + netlify
| Joe8Bit wrote:
| 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/
| kaycebasques wrote:
| 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.
| marvinblum wrote:
| I like Hugo. You can chose any of the existing themes or create
| your own. For deployment, I wrote a simple Go server that checks
| a (public) GitHub repo for changes every 15 minutes and pulls +
| regenerates the content if necessary.
|
| You can find it here: https://docs.pirsch.io
| verdverm wrote:
| Big fan of Hugo too
|
| https://cuetorials.com
|
| https://github.com/hofstadter-io/cuetorials.com
| crossworth wrote:
| I like Hugo as well, I'm using https://getdoks.org/
| auspex wrote:
| Anyone know of a good hosted documentation that allows you to
| password protect the docs for a startup? (We don't want public
| documentation and want to control access per user)
| rahimnathwani wrote:
| You can use whatever documentation software you want, and let
| the web server handle access control:
|
| https://docs.nginx.com/nginx/admin-guide/security-controls/c...
|
| You can Google 'nginx reverse proxy authentication' to find
| guides.
| DarthNebo wrote:
| Recently found "Just The Docs" https://pmarsceill.github.io/just-
| the-docs
|
| It even incorporates search with every build.
| gk1 wrote:
| We use Redoc.ly (https://www.redoc.ly) which has both a self-
| hosted and a managed version. I like that it integrates with
| GitHub, generates API Reference docs based on OpenAPI specs. It
| also has a "developer portal" for user guides, generated from
| markdown. All-in-all makes it easy to publish great-looking docs.
|
| Preview: https://www.pinecone.io/docs/
| eduardosasso wrote:
| Not sure if you can self host but I had a good experience using
| gitbook.com on my latest project hotstoks.com
| davidandgoliath wrote:
| Mkdocs.
| robbiejs wrote:
| I have a custom setup. I don't use a generator. I don't like my
| JS files with all these doc-comments.
|
| The downside: quite a lot of work to create something from
| scratch.
|
| The upside: I have created a playground-type API, where all
| options, methods & events can be tried out directly from the
| docs. They interact with the data grid.
|
| https://www.datagridxl.com/api/options
| superzamp wrote:
| We're using readme.com for https://docs.numary.com/
|
| Pretty satisfied with the productivity gain and the API docs
| generation from our OpenAPI file.
|
| I just learned that their API would allow us to programmatically
| update the guide section as well, so we'll probably move the
| guides to a public github as well for contributions.
| Jefro118 wrote:
| In case you're using Google docs/drive for docs at the moment,
| I've built https://neat.wiki for precisely this purpose. If it's
| documentation for code there are better options though.
| grodriguez100 wrote:
| Very similar, but free: https://spaceli.io/
| austincheney wrote:
| I am frequently working on ways to document inline with the code
| using comments and then extract those comments during the build
| process to keep documentation up to date automatically. The
| comments are formatted as mark down so that they may be converted
| from code comments to stand alone mark down documents.
|
| I have also noticed that in VS Code a comment immediately
| preceding a type or interface declaration written in mark down
| format becomes formatted markdown in the tooltip where that type
| is used.
| pcthrowaway wrote:
| Are you talking about Typescript here? If so, could you give an
| example of how to make this happen? This sounds incredibly
| useful.
| loh wrote:
| I think you and austincheney might be looking for
| [TypeDoc](https://typedoc.org/). See my comment here:
| https://news.ycombinator.com/item?id=29265856
| plondon514 wrote:
| Using https://docusaurus.io/ for my side project codeamigo. It's
| been great, although arguably I need to add more to the docs :)
| samcrawford wrote:
| https://www.mkdocs.org/. Probably not the latest or greatest, but
| it produces nice looking documentation from markdown. Serves my
| purposes well.
| navaneethpk wrote:
| 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/
| grodriguez100 wrote:
| Aspect ratio of screenshots looks wrong when the docs are
| browsed from mobile phones. Is this a docusaurus issue or
| perhaps specific to your docs?
| navaneethpk wrote:
| I think it is because we have explicitly set the height of
| the images (https://github.com/ToolJet/ToolJet/blob/develop/d
| ocs/docs/in...). Will fix it.
| shafyy wrote:
| I'm also using Docusaurus for Fugu (https://docs.fugu.lol).
|
| One thing that bothers me is that they offer a free Algolia
| integration for open-source projects, but they declined my
| application despite being open source.
|
| So, search not working for now, need to have another look at
| that :-)
|
| Edit: I just got an email from Algolia DocSearch saying that my
| documentation qualifies after all :-) If someone from that team
| read my comment and send the email, thanks! If not, it's a big
| coincidence, also good!
| stavros wrote:
| It doesn't support search unless you rely on (pay for)
| Algolia? Wow, instant pass from me.
| shafyy wrote:
| You can add your own search plugin or use another provider
| like Typesense. They just offer an optional free Algolia
| service for open-source projects on top. You can read more
| here: https://docusaurus.io/docs/search
| stavros wrote:
| Ah phew, thanks. The site made it sound like they only
| supported Algolia.
| navaneethpk wrote:
| We tried to use Typesense for the search bar. We could not
| wrap up the PR due to bandwidth issues but it should be a
| great alternative for Algolia. Link:
| https://github.com/typesense/typesense-docsearch-scraper
| shafyy wrote:
| Yes, that looks like a good solution! Thanks!
| akajla wrote:
| +1 for Docusaurus. We're using it at Warrant
| (https://docs.warrant.dev/). In addition to what folks have
| already mentioned, it has good blogging support as well
| (markdown, post tags, SEO/social tags etc). Makes it much
| easier to manage both docs + blog from the same system.
| lelandfe wrote:
| > live documentation: https://docs.tooljet.io
|
| The two separate hamburger menus were hard to parse at first on
| mobile. Do your social media links really deserve higher
| placement than the navigation?
| stavros wrote:
| Oh huh, I completely missed the second hamburger button and
| was perplexed as to why their documentation only had three
| links to other sites.
| navaneethpk wrote:
| You are right, placing the navigation on the sidebar is more
| useful than the links to GitHub and Slack.
| dsmmcken wrote:
| Update to a more recent version, they re-worked the nav to
| be one menu on mobile.
| navaneethpk wrote:
| Your comment was super helpful. I just tried upgrading to
| 2.0.0-beta.9. The menu now looks great on mobile. The
| upgrade is causing some other issues, will fix those and
| deploy the docs. Thanks!
| navaneethpk wrote:
| That was a very low-hanging fruit. Could fix and deploy
| it in a few minutes. There are few other improvements too
| related to navigation in the latest Docusaurus. Deployed
| here: https://docs.tooljet.com
| lelandfe wrote:
| Much better, thanks!
| gompertz wrote:
| Sort of curious, is there key differences between Docusauras
| and Hugo that would make it worth switching??
| daviesliu wrote:
| Docusaurus is great! We migrated from Sphinx to Docusaurus[1]
| recently, the navigation is much better than before.
|
| One thing that bothers us: we have not figure a way to name the
| anchor that both work in Github (`<span id='aws-s3'/>`) and
| Docusaurus (`{#aws-s3}`), for example [2]. Any ideas?
|
| [1] https://juicefs.com/docs/community/introduction [2]
| https://github.com/juicedata/juicefs/blob/main/docs/en/how_t...
| dsmmcken wrote:
| Not a great solution, but you could create the links github
| style, then write a remark/rehype plugin that transforms them
| to Docusaurus style at build time. I would probably just live
| with it though.
| kaycebasques wrote:
| What was your motivation(s) for migrating away from Sphinx?
| navaneethpk wrote:
| Haven't tried this but will it work on both GitHub and
| Docusaurus if the section "S3" is renamed as "Amazon S3" and
| then removing the "{#aws-s3}" part?
| daviesliu wrote:
| Yes, we can use `#amazon-s3` as the anchor, then the name
| could be long, for example, `#digitalocean-spaces-object-
| storage`), and it will not work in Chinese.
|
| Your suggestion is better than current one, we will use
| that, thanks!
| newaccount74 wrote:
| Your docs even support dark mode! Did that come out of the box
| or did you add that?
| navaneethpk wrote:
| It comes out of the box. We are now trying to figure out how
| to switch screenshots based on the light/dark mode. The
| screenshots taken from light mode of ToolJet looks odd in
| Docusaurus' dark mode.
| dsmmcken wrote:
| You could build your own react image wrapper then use that
| component in the mdx and pass in two images, then display
| the appropriate one based on the current theme provider.
| Docusaurus makes using inline react components easy.
|
| You could also write your own remark plugin, that does it
| for you, and would have the benefit of having more control
| over what happens on the github side if it was still
| standard markdown.
| navaneethpk wrote:
| Thanks, I will try creating a custom react component for
| handling the modes.
| dsmmcken wrote:
| We also use Docusaurus. It has good defaults. If you are
| familiar with react, mdx (markdown + jsx) allows you to easily
| create and embed interactive react components.
|
| It's technically still in beta with frequent updates, and the
| occasional breaking change.
|
| For our site (https://deephaven.io/core/docs/), what I liked
| was the ease of adding your own plugins. We made a plugin that
| extracts all our code examples, and automatically tests them
| against new versions to notify us if any examples break or
| become stale.
| zabil wrote:
| For my project I use eleventy with markdown and commit to github
| which then deploys on netlify.
|
| To make it very easy to navigate the documentation it's
| integrated with docsearch(algolia).
|
| All of this is free for open source projects.
| jaredtking wrote:
| We recently switched from a custom markdown setup to Archbee
| (https://archbee.io) for our user and developer documentation.
| Our team loves it!
|
| Here is our Archbee-hosted site: https://docs.invoiced.com/
| LeonB wrote:
| I'm using clowncar:
|
| https://github.com/secretGeek/clowncar
|
| ...to turn markdown files into my "today I learned" site, here:
|
| https://til.secretgeek.net/
| lizparody wrote:
| We are using Dash ReadMe (https://dash.readme.com/login) - Easy
| to configure - Beautiful UX/UI - Good documentation
| h3rald wrote:
| 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 go into, if you
| like unusual programming languages)
|
| Examples can be found in the docs listed for most of my with my
| projects, here:
|
| https://h3rald.com/projects
|
| The only thing missing from those is search, but I could plug in
| LiteStore[4] and be done with it. OK, I think that's enough self-
| promotion for one comment, but you did ask...
|
| [1] https://h3rald.com/hastyscribe/
|
| [2] https://h3rald.com/hastysite/
|
| [3] https://h3rald.com/min/
|
| [4] https://h3rald.com/litestore/
| kaycebasques wrote:
| 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?
| h3rald wrote:
| They are features of the documentation system itself, here's
| a simple example of macros:
|
| 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.
| ..
| kaycebasques wrote:
| Background: I've been a technical writer for 9 years. 6 at
| Google, 3 as the only writer at an IoT startup.
|
| I helped Corrily with their docs [1] in August. They were
| interested in ReadMe.io. I wasn't keen on it because I had worked
| with Retool on their docs (hosted in ReadMe) a few years back and
| had found ReadMe lacking. But I was pleasantly surprised by how
| much it has progressed since then! If you're looking for a
| documentation product that is very easy to update and mostly just
| works, then it's worth checking out. The pricing structure gets
| steep very quickly though.
|
| On https://web.dev I was introduced to Eleventy. Eleventy [2] is
| now my go to. The documentation for Eleventy itself is very
| strangely organized and needs a refactor. But I have found that
| there is always a way to accomplish whatever I need, and usually
| elegantly. Eleventy requires a lot of customization and probably
| wouldn't be a great fit for a huge contributor group with varying
| technical skill. If you're working solo or with a small team of
| technical people and need to do some deep customization it can be
| great.
|
| Another project worth checking out is Docsy [3]. This is a Jekyll
| template specifically created for technical documentation.
|
| Back at the IoT startup I had to set up the whole documentation
| system / tooling myself. I used Sphinx [4] and deployed to
| Heroku. Haven't used Sphinx since then but I remember being
| satisfied with it back then. reStructuredText, the flavor (?) of
| Markdown Sphinx uses, has some very nice features. I remember
| they had a very intuitive way to create tables. CSV format, I
| think... Again I was mostly updating the docs solo so "ease of
| contributing" wasn't a deciding factor (although when I left they
| might have struggled to update the docs, so maybe ease of
| contributing should always be a key factor).
|
| I'll strike while the iron is hot here and mention that I'll
| probably be back on market in March - April and love to set up
| documentation systems (as well as write docs of course) if your
| company needs help with that. Poke around on my website (link in
| HN bio) to find my contact.
|
| Edit: I left another comment in this thread cautioning to be
| careful when choosing a doc tool:
| https://news.ycombinator.com/item?id=29266957
|
| [1] https://docs.corrily.com
|
| [2] https://11ty.dev
|
| [3] https://docsy.dev
|
| [4] https://www.sphinx-doc.org/en/master/
| geocrasher wrote:
| I did some freelance technical writing a while back and the
| customer was using readme.io. It has its quirks but at the end
| of the day I ended up really liking it and will likely use it
| again for such projects.
| luizfelberti wrote:
| I've found https://js.wiki to be pretty good
| stichers wrote:
| Basic markdown and Sphinx to build into HTML, publishing via
| github pages. It's an open source project so putting the docs
| alongside the code just makes sense. Although Sphinx isn't great
| for my money, it gets the job done.
| ak217 wrote:
| I use this combination too, and I love it. Sphinx has great
| hackability and support, while github pages is free and very
| reliable. Here is a script that I use to publish to github
| pages, assuming the sphinx config is under "docs":
| sphinx-build docs docs/html git branch -D gh-pages ||
| true git checkout -B gh-pages-stage touch
| docs/html/.nojekyll git add --force docs/html
| git commit -m "Docs" git push --force origin $(git
| subtree split --prefix docs/html --branch gh-
| pages):refs/heads/gh-pages git checkout -
| acidburnNSA wrote:
| I have grown to absolutely love Sphinx. The plugins are
| wonderful, including Sphinx gallery, jupyter integration, and
| Sphinx-needs for requirements management.
| stichers wrote:
| I think it grows on you. There's a way to work with it and if
| you settle on that, it makes it easier than fighting against
| the prevailing tide. I find I spend a lot of time looking up
| opaque build errors but that is partly because the
| contributing authors aren't all that familiar with it, so
| their markdown is less than 'pure'
| byteface wrote:
| I also use sphinx and https://readthedocs.org/. lots of sphinx
| repos are open source so you can use them for inspiration...
| https://www.sphinx-doc.org/en/master/examples.html
| dabeeeenster wrote:
| We [1] moved from mkdocs to docusaurus v2 and couldnt be happier.
| Very active project with a great community, and enough
| flexibility and config overrides when we need it.
|
| [1] https://docs.flagsmith.com/
| jacobmischka wrote:
| mdBook (or Gitbook) is also an option. A bit more general than
| just for docs, though they advertise it as a first class use
| case.
|
| https://github.com/rust-lang/mdBook
| jomar wrote:
| A small Perl script <https://github.com/jmarshall/manconvert>
| that grinds a subset of man page nroff syntax directly into HTML.
| (That subset being "the constructs that are used in the man pages
| that it's used on".)
|
| Some of the styling could be improved (those section headings for
| one!), but IMHO it produces better results than other more
| general-purpose manpage to HTML converters: see e.g.
| <https://www.htslib.org/doc/samtools.html>.
| loh wrote:
| We use [TypeDoc](https://typedoc.org/) to generate documentation
| from all of our TypeScript. It combines type definitions with
| surrounding comment blocks for easily navigable, clean
| documentation.
|
| For non-TypeScript codebases, we use
| [Docusaurus](https://docusaurus.io/).
|
| I believe there are also plugins which can make TypeDoc output
| compatible with Docusaurus.
|
| None of our docs are public at the moment, but a good example of
| documentation generated by TypeDoc would be Amazon's `aws-sdk`:
| https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/index...
| Symbiote wrote:
| 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/
| davidwf wrote:
| Really really love Antora. I've been pushing hard for it for
| internal docs -- one very nice attribute is that it can collate
| docs from multiple Git repos. This way, you can have
| documentation close to the code, like I want as a developer,
| while having a single "documentation site" like most management
| and non-technical users want.
| 255kb wrote:
| We have an handmade website using Next.js. It generate the
| documentation from the markdown files present in the `content`
| folder. It was not the easiest path, but it does the job.
|
| Code: https://github.com/mockoon/mockoon.com Preview:
| https://mockoon.com/docs/latest/
| diveanon wrote:
| Curious about why html/css is the default option here, its seems
| like something that is easier to save offline would dominate.
| jrudolph wrote:
| TL;DR: Favorite stack is Notion -> notion-markdown-cms ->
| VuePress -> netlify
|
| So I've gone through a bit of journey doing docs for a product
| company. I feel that for a product company it's really important
| to own your documentation and the publishing workflow as it's a
| key part of your product.
|
| GitBooks was my first stab. I liked git and markdown, however I
| disliked all the places where "proprietary" formatting/features
| crept in and once it got more closed/commercial wrt.
| publishing/theming pipeline we went out.
|
| We then adopted docusaurus v1 for our product documentation. It's
| a great tool, but never really built custom components for it
| because we're not a react shop. We did integrate some nice tools
| to work with our markdown tool (e.g. markdown-lint, custom code
| snippet injectors etc). One downside of docusaurus is how much
| friction there is to create a new page. You have to create a
| markdown file, insert frontmatter, add it to sidebars.json,
| reload the dev server, then insert your content.
|
| When docusaurus announced v2, we considered adopting it. Instead,
| we started looking into VuePress vNext. What I love about it is
| that its configuration is TypeScript (vs. JSON). This allows us
| to generate things like navbars, sidebars from code instead of
| manually wrangling JSON. It uses Vite for bundling and the local
| editing experience is therefore much faster.
|
| As you write more and more docs, markdown editing experience
| becomes important. VSCode + the right plugins can get you far,
| but we found they all did not feel "fluent" to the point where
| our team _loves_ writing documentation. People often complained
| that our company wiki (Notion) feels much nicer, so we built a
| tool that allows us to use Notion as a "CMS" for our
| documentation: https://github.com/meshcloud/notion-markdown-cms
| It's really handy because that way we get perks like organizing
| content with databases, link pages using @mention syntax, drag &
| drop for screenshots etc. Publishing on netlify rounds it off.
| kaycebasques wrote:
| Thanks for the context. Which docs system one chooses is really
| dependent on that person's specific goals / product so it's
| helpful to see your detailed thinking here.
| parkersweb wrote:
| I've not used it yet - but planning to give Nextra
| (https://nextra.vercel.app/) a go next time around.
|
| The 'docs' theme is intended as a quick way to produce a
| documentation website based on Next, which you can obviously
| customise further with your own components if needed.
| eatonphil wrote:
| A markdown generator embeds markdown from a Github repo into the
| marketing site. This way the marketing site is kept private while
| anyone can easily contribute to docs.
|
| Docs are kept in separate folders for each release.
|
| https://github.com/multiprocessio/datastation-documentation
| hermitcrab wrote:
| I used Help and Manual to document my software:
| https://www.helpandmanual.com/
|
| It can generate HTML, CHM, PDF etc, all from a single source.
|
| It is one of my favourite software tools (I am a customer and
| have no financial interest in it).
| tomw1808 wrote:
| 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
| twalla wrote:
| Another happy user of mkdocs, also really like gitbook. If I
| had to choose something for people who didn't like
| git/plaintext and wanted richer embeds, I think I'd suggest
| Notion.
| 4kelly wrote:
| +1 for Material MkDocs. It's beautiful and functional by
| default so I can just focus on documenting.
| evolve2k wrote:
| Oh wow this looks great! Simple conversion of markdown into an
| opinionated simple to use really nice looking doc site.!
|
| Cheers for this :)
| sixhobbits wrote:
| +1000 for the "Material for MkDocs" project by squidfunk - we
| (Ritza.co) do documentation for various companies and we've
| strongly encouraged them to all switch to this since we found
| it. Fast, beautiful, simple.
|
| The free version is really nice but also very happy to pay
| for the 'insiders' version via GitHub donations.
| squidfunk wrote:
| Thanks for your continued support!
| tedyoung wrote:
| Another +1 from me for mkdocs and mkdocs-material (and I'm also
| a supporter of squidfunk). I use it for lab exercises[1] as
| part of my online courses (deployed onto Netlify). It just
| works and looks good.
|
| [1] https://moretestable.com
| 015a wrote:
| Material Mkdocs
|
| https://squidfunk.github.io/mkdocs-material/getting-started/
| fenesiistvan wrote:
| MS Word converted with some tools to html, chm, pdf.
| perfopt wrote:
| Is there anything that supports languages other than English -
| specifically Indian languages. I am writing documentation (book)
| to be distributed online. I presently use mdbook but markdown
| does not support anything other than English.
| Symbiote wrote:
| What do you mean by Markdown not supporting other languages? I
| don't see how it wouldn't support other languages.
|
| Although we're using Asciidoctor (syntax / markup language)
| with Antora (tooling) ourselves, including with a Chinese
| translation. It's similar to the Fedora documentation:
|
| https://docs.fedoraproject.org/ur_PK/docs/ (Urdu? Most
| translations are very incomplete; it's just volunteers.)
| woudsma wrote:
| As others in this thread have mentioned, Docusaurus is really
| good. It was very easy to add search with Algolia and meta tags
| for SEO as well.
___________________________________________________________________
(page generated 2021-11-18 23:04 UTC)