📝 Doc of Docs

[AntoLC]

Feature Request

As we said, we will improve the documentation of Docs with md files, in the root/documentations folder.
We can still make it more user friendly, to do it it exist https://github.com/docsifyjs/docsify .
docsify will parse the documentation folder and make a website from it, we can do theming with it to brand it La Suite.
We can then set this website on our repo github with github-pages, on a special branch.

Demo

Here it showcases that we can achieve with it: https://github.com/docsifyjs/awesome-docsify?tab=readme-ov-file#showcase

[sampaccoud]

I think it should be root/documentation (no "s")

[virgile-dev]

Hey @AntoLC
@arnaud-robin recommended checking out https://nextra.site/
Also do we want to have a website for documentation at this stage where we don't have so much content ?

[xibe]

Hi! Can I help? I'm a tech writer by trade, and I see there's no user documentation available (apart from the Architecture & Installation ones). I might be able to have spare brainpower for this part of the Docs project (depending on spare time).

In terms of tooling, @AntoLC suggests Docsify, while @virgile-dev & @arnaud-robin mention Nextra. Browsing their respective showcases, it seems to me that they both are great for developer documentation, but not so much for user documentation. Nextra has the advantage of being built using Next.js, which is already in the toolbox of the Docs developers.

There are of course of host of open-source, Markdown-supporting, React-based solutions to choose from! For instance: Docusaurus, MkDocs, Gatsby, or Starlight, for starters. Of course, some big players in the Serious Tech Writing circle are Sphynx and Doxygen.

Things to look at besides the technology are:

• Needs: Do you want a tool for user documentation, developer documentation, or both?
• Community & long-term support:
• • For instance, Gatsby seems nice but its contribution chart is decreasing and the future seems uncertain. Same for Docsify, sadly. Same for GH Pages' Jekyll.
• • On the other hand, Docusaurus receives rather steady contributions (and is supported by Facebook, which can be seen as a con of course), MkDocs' chart seems spotty, and Starlight seems nice.
• Content format(s): Markdown is a favorite and makes it easy to contribute quickly; reStructuredText and AsciiDocs is like by some but might imply to learn new syntax for some, which could lower the contribution numbers.
• Key features: Search, theming, versioning, performance, 3rd-party integration, etc.

I've seen a lot of good stuff on the Docusaurus side (for instance at Swan), but I've never used it directly myself.

Also, since you're on GitHub already, there's also GitHub Pages (Jekyll-based) and GitHub Wiki, which has the benefit of not having to deal with the maintenance of 3rd-party tools.

And, of course, how about eating your own dog food instead of using another tool? 😇 Can Docs be used to manage public pages already? If not, could this be an early project target, for dogfooding reasons?

Anyway, I feel there should be an informed discussion about tooling before making a choice that the Docs team will have to leave with for a long time. If I can help, let me know!

[bzg]

In terms of "dsfr-ready" solutions, we use mkdocs for code.gouv.fr documentation and we developed & used docsify-dsfr-template.

My suggestion would be to first decide who will maintain the doc then let this person decide what tool to use.

If it was me, I'd start with GitHub's wiki developer-oriented doc and docsify for user-oriented doc.

[ForsakenHarmony]

There's also mdBook (single executable) which you can very easily put on GitHub pages.

(And I suppose GitBook)

[virgile-dev]

Hey @xibe !
Thanks for proposing your help.
My current stand on this is

• Technical docs : sources in the repo and eventually a website using these sources (tech stack to define)
• User docs : dog fooding
  For user docs I have this minimalist doc : https://docs.numerique.gouv.fr/docs/a3acb1df-f98d-426e-a69b-6b9c6220c3b2/
  Would love to improve it!

[xibe]

Oooh, nice, so dogfooding is already possible! 👌
And indeed, that's probably the best option for user guides, given the possibility to test right away.

For tech docs, the docs-as-code approach supposes that the tech stack is mastered by several members of the team, and that the stack automates as many moving parts as possible (for instance, merging a doc-changing PR triggers a workflow to update the live site).
It would be best to rely on tooling that is already in-use within the Docs community, or the larger DINUM community. For these reasons, I like what @bzg says: If something's already working nearby, Docs should probably capitalize on it.

[xibe]

@ForsakenHarmony

There's also mdBook (single executable) which you can very easily put on GitHub pages.

As far as I can tell, mdBook seems to produce the same kind of content (design-wise) than other solutions cited, but with a different stack, based on Rust. I don't know what the Docs guys use, but that would be adding another tech constraint to managing this aspect.

(And I suppose GitBook)

GitBook is nice for tech docs, but is proprietary, not very customizable, and for-pay.

[PovilasID]

I think that Docs documentation should be using Docs. It would be a grate showcase of the project.

To accept documentation contributions via github pull requests I think they should set up a S3 git sync workflow. Something similar to this https://github.com/enamhasan/GitHub-S3-Sync
This should theoretically be possible because Docs documents are just files in S3 bucket.

However, for something more than fixing a spelling mistake this would require contributors to fork the repo and change the sync form official S3 bucket to theirs so that they could edit documentation in docs then back from S3 to fork and finally in a PR. A bit more steps.