Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question

closed as off-topic by gnat, Thomas Owens Apr 17 at 11:50

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "Questions asking us to recommend a tool, library or favorite off-site resource are off-topic for Programmers as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it." – gnat, Thomas Owens
If this question can be reworded to fit the rules in the help center, please edit the question.

3 Answers 3

up vote 2 down vote accepted

I can recommend Trac.

Regarding your requirements:

  1. Portability: The syntax used is fairly standard and there exist tools to get the wiki articles exported.

  2. Easy to use: The system is very intuitive to use. Images are supported, the syntax is easy to remember and feels natural. There is a WYSIWYG mode where you see the formatted content while you type markdown just like in StackExchange.

  3. Code Expressions: Geared towards programmers, Trac natively supports inline code blocks which are syntax highlighted automatically.

  4. Integrate with API documents: I don't know if there is a specific module which allows you to tightly integrate API documentation and overview. However, the following possibilities exist:

    • Define your own URL types, e.g. [pydoc:Class/Method] which is then mapped to whatever URL your pydoc uses.
    • Find an existing module on TrackHacks.
    • Write your own module. This requires less time than you probably think.
  5. Other concerns: Trac is a platform that is extremely easy to extend. If you happen to come up with further requirements in the future, it won't cost you a lot to integrate that functionality in Trac even if it does not yet exist. It is also easily customizable, i.e. you can tailor it down to your specific needs. For example, if you don't need the code repository module, you can simply unload it.

share|improve this answer

I totally agree with Simon Stelling on his points. Trac is a great tool that I've used several times for having nearly every aspect of a project in a centralized location. However, there are other tools out there.

Another tool that you can consider would be Redmine. For some of the features that you want (such as portability), you'll need to customize it with plugins. I don't have significant experience with Redmine, as I've only used it once, but I thought it was pretty stable and reliable, and it did get the job done in terms of fostering to-do lists, documentation, bug reports, and so on.

Again, Redmine is built to be a one-stop-shop for project information, ranging from the scheduling/task tracking all the way through source code and documentation. This might be a little overkill, but I enjoy having tools like this at my disposal.

share|improve this answer
1  
Agreed. Redmine is the Trac for people who prefer to write modules in Ruby rather than Python. –  blubb Jul 31 '11 at 12:38
  • I suggested WordPress in my answer to knowledge base/collaboration tools?.
  • Trac is not really a knowledge base management system but an issue tracking system.
    • You're gonna need it anyway, it's not an alternative to a KB.
    • Remember that in a tracking system it's important to see over time what changes to a project happened where, while in a knowledge base system it's important to see what is current and how it works, plus absolutely anything you can think of that matters to a project and to a company.
share|improve this answer
1  
Trac is a project management system that incorporates a wiki, scheduling, bug tracking, and source code control integration. It's pretty much a one-stop-shop for all information about your project. –  Thomas Owens Jul 31 '11 at 12:11
    
Trac is far more than an issue tracking system. It makes it just as easy to see what the current state is as it is to investigate changes over time. –  blubb Jul 31 '11 at 12:36
    
A knowledge base is not a tool for project management but a reference. (A tracking system is needed in any case). –  Ando Jul 31 '11 at 12:37
1  
@Andrea The wiki components of Trac and Redmine are suitable for KM. In addition, the current state of bugs, issues, tasks, and the source code are indeed part of the knowledge needed by various people involved in the project. –  Thomas Owens Jul 31 '11 at 13:03

Not the answer you're looking for? Browse other questions tagged or ask your own question.