Software documentation platform

Writing in English for our friends from abroad that might also help with this. I’m searching for a software documentation platform/solution for two free open source projects that I’m heavily involved. From my understanding right now the alternatives that are not considered proprietary are:

  • Github wiki pages (pros: the same place where the code of the software lives);
  • mediawiki installation (needs a dedicated server and sysadmin working time);
  • https://readthedocs.org/ (found this recently).

This is from my quick research and from e person that has not done much software documentation work in the past. Your opinions and examples of documentation of free open source projects would help me take a decision on this. Keep in mind that we are talking for small projects that will hopefully need scalability features in the future. Many thanks.

2 Likes

I seems that Facebook also has a documentation platform which can be used and it is open source: https://docusaurus.io/. Has anyone used it?

R.S

I would discourage from using MediaWiki at all since it’s not really dynamic and on the same pace as git. It also has a database, which is unneeded for documentation.

Chris Ward aka Chris Chinchilla knows a lot about Read the Docs so he would be a great person to ask. I heard good things.

Having your Docs on your GitHub Wiki is also really time saving as you can create a GitHube page for the docs as well out of the box:
https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/

1 Like

Hello @rskikuli,

That’s indeed a “though” question with no real and definitive answer … It really depends on the project !
Is it technical documentation ? Is it a user manual ? Is it a contribution manual ? …

If it is technical documentation about the code itself, there are some libraries that generates documentation automatically from the comments inside the source code (PHP: https://phpdoc.org/, JavaScript: http://usejsdoc.org/, …). That’s usually really easy and pushes you to comment your source code properly.

If it is more user manual or contribution documentation, I would suggest to use GitHub pages. I guess your source code will be hosted on GitHub, so you don’t have to bother with hosting, …
You can make something simple just by using Markdown (https://guides.github.com/features/mastering-markdown/) or something more “fancy” using Jekyll (https://help.github.com/articles/using-jekyll-as-a-static-site-generator-with-github-pages/).

“Read the docs” platform is a good and used platform. If you use Markdown (or reStructuredText) for your documentation on GitHub, you can just link “Read the docs” with your documentation and “Read the docs” will be automatically updated every time you update your repository !

There are my 5 cents about the topic :stuck_out_tongue:

4 Likes

Fedora is utilizing AsciiBinder. It’s rapidly evolving but is designed for projects that will scale. More work will be happening during the Fedora Docs FAD later this month.

The underpinnings are a gift driven workflow of AsciiDoc files processed into a static site.

4 Likes

I also think the “what” of what you’re documenting matters most and should drive the conversation for what tool or platform to use. People have favorites for different reasons, and your use case may make one platform a better choice for what you’re doing.

My favorite is Sphinx (which is what platforms like ReadTheDocs host for you).

Sphinx is a documentation tool that works with reStructuredText source files for documentation. Sphinx is used by Python documentation, Blender, OpenCV, and various Mozilla projects [1]. Using Sphinx leaves you the option to use a platform like GitHub Pages or ReadTheDocs to host your Sphinx-based documents. This also benefits Open Labs by not requiring the addition of new infrastructure.

In Sphinx, your documentation lives in the git repository, just like the rest of your code. You can write and build your docs in the same repo as your project, which also makes it easier for others to contribute to (a pull request). There are localization options but I have not looked into it. It’s a Python-based tool and works powerfully for Python programs, but also works nicely with others (like JavaScript). I also use it write non-technical content too, like my university’s open source club runbook.

I have enjoyed working with Sphinx and ReadTheDocs for my documentation, but I’ve only worked with markdown or wikis as my prior experience before I found Sphinx.

3 Likes

Well, sadly, much like a coding question, there are LOADS of options. It really depends on what you want, what language you’re most comfortable with for customisation etc.

Read the Docs / Sphinx possibly has slightly higher learning curve, but will handle more requirements in the long run such as versioning, customisations, extensions etc. It’s also well established in the tech writer community, and also behind write the docs etc.

If you are happy with something simple then just using Markdown / RST / etc and a static site generator might be enough for you.

Do you also want to document APIs and use an API spec? Because then there are also tools that handle both of those. I have been using DocFX from Microsoft recently (OSS) and really liking it. I haven’t looked at Docusaurus yet, but it’s on my list.

I would avoid the wiki path really, as it keeps the docs and the codebase too separate.

I sense a talk proposal for a certain conference :thinking:

5 Likes