Imagine your ideal documentation and support site - what does it look like?

Discussion Zone
, , ,
1

Imagine that there exists a server where you go to collaboratively create documentation. It’s a place where you can ask questions (and be taken to a spot in an article if an answer exists) or you can request a new topic to be written about, or do it yourself. The articles themselves are the latest versions of a templated GitHub repository, meaning that all current and previous edits are under version control. Permissions are handled via GitHub, so if anyone that has an account on GitHub can easily contribute. The content of the site is completely open for anyone to read, regardless of that. The organizational or individual owners of the repository, by way of creating a topic or concept, are in charge of its curation, so the site is distributed. And there are ways (via the API) for you to connect with the server for your tools or users to easily query it.

It’s a bit like a wiki combined with version control to provide a base for documentation and support, but without having separate posts for a question, and without having the “dog eat dog” mentality of a stack overflow. “Voting” is implicit in the collaborative work done over time to improve a concept. Other important details:

  • the entire site could be exported and re-created simply as a list of GitHub repositories that populate the content.
  • templates for the repositories could be customized to allow for different types of content

Does this sound interesting to you? What features would be important? Should there be organization of topics or concepts, or should they be placed under a “library” namespace akin to Docker Hub? How should groups (not permissions) be organized? What would make it fun? What would you worry about? What tools might you build from it?

Any thoughts, ideas, questions, please post! I’ve been thinking about this idea since 2017, and there still aren’t good solutions out there, so we should do something about that.

2

This sounds fantastic.

The most important feature for me would be a first-class search experience. I attempted to capture some of my nascent thoughts about better search of support forums etc. for open source projects in the following places:

3

For those following along here, I have a dummy server deployed with an early idea for what I have in mind - this version controlled, collaborative documentation server -> https://askci.dev/.

Learn more about it at https://vsoch.github.io/askci. Basically, it’s distributed because anyone that logs in with GitHub owner can take charge to maintain a particular documentation repository, and if the server goes down, the repos live on. But it’s also centralized because the server acts as a single entry point to search, link to questions, etc. It’s still hugely under development so you can expect changes, bugs, and the occasional server restart! Rest assured that I have Sentry set up so any error you trigger will notify me asap.

I’d like to get this a little more developed, create the helpme command line tool to interact with the API, and then (hopefully) have enough discussion with @jma to decide if this should be branded under AskCI, or if it’s something entirely different.