I'm founder of a web-site called Now.in. I wrote all programs by my-self at first. And we are going to run a start-up company. More people will soon get involved. Some know-how/overviews only exist in my mind, it takes time to explain to newcomers. Hence, I would like to write some documents for others to read. Here comes the problem, how to write documents? Which tool/platform should I use?
I have some concern in my mind.
For sure I can just write documents in Google Docs, run a Wiki, or even use wiki of BitBucket repo directly. But the problem is, what if I would like to use another document system rather than current one? It would be difficult and costly to convert documents among markdown languages/Google Docs.
Easy to use
Diagrams are important in documents for explaining something. Some of simple wiki/doc system doesn't support uploading images. You can upload the image somewhere else and insert the image tag in documents, which is kinda inconvenient to use.
Also, it appears some of those markdown languages are difficult to learn and remember. I don't like to spend one month to learn something looks like LaTeX and start to write document, which will drive me crazy. Simple and expressive markdown/WYSIWYG would be nice.
Google Doc is easy to use and powerful enough. But however, sometimes I would like to write code example in documents. It's good to have syntax highlight. But for Google Doc, it's not friendly to write code there.
Be code friendly, would be a nice to have feature, too.
Integrate with API documents
For overview/SOP/Know-how documents, it's fine to write them directly in the document system. But for my Python code base, there might be some generated API-level documents from those code. It would be inconvenient to have two documents system, one for API and one for overviews. So, I think it would be nice to have them integrated together.
So.... What to use?
Maybe I have some more concerns in my mind, but I can't recall them in this moment. I would like to know what kind of document system you are using? Would you recommend some? It's fine even if it takes some fee to use the platform/system, we can afford if it is not too expensive.