Pergunta

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 concerns.

Portability

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 the current one? It would be difficult and costly to convert documents among markdown languages/Google Docs.

Easy to use

Diagrams are important in documents to explain things. Some of the simple wiki/doc systems don'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 that looks like LaTeX and start to write a document, which will drive me crazy. Simple and expressive markdown/WYSIWYG would be nice.

Code expression

Google Doc is easy to use and powerful enough. But however, sometimes I would like to write code examples in documents. It's good to have syntax highlighting. But Google Doc isn't user friendly for code writing.

Being 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 codes. It would be inconvenient to have two documents systems, 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 at this moment. I would like to know what kind of document system you are using? Could 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.

Nenhuma solução correta

Licenciado em: CC-BY-SA com atribuição
scroll top