Redmine

I'm going to take this as a no.

Hi,

Sorry nobody answered before. I cannot let you answer yourself alone in the dark, so here are some thoughts about your questions from an (occasional) core contributor.

1/ Mediawiki does a fantastic job at documenting their code. In Redmine the problem is there's not a lot of contributors (3 permanents contributors, and less than 5 or 6 occasional like me), so we're focusing on fixing things, achieving new features, and (honestly) not much about documenting. All the official documentation is on the wiki. The wiki also includes a lot of contributions for volunteers, mostly translations for original guides or step-by-step tutorials for installing Redmine (just see the index by title).

• documentation for plugin developers (I'm particularly interested in that ; feel free to ping me on twitter or by email, add new issues and assign them to me here, etc.)
• documentation for the REST API, which should be as exhaustive as possible if we want 3rd party libraries to build reliable things on it (such as native mobile apps)

• Ruby on Rails is full of conventions and Redmine is in many areas a good, standard Rails application, which means repecting the conventions doesn't call any more documentation
• maintaining a documentation about features is impossible to maintain outside the code (in wiki pages..) ; it should definitely be maintained inside the source code but it's pretty hard too to focus on so many things ; often features are "documented" with an associated test suite, which is better than the opposite (a doc but no tests), even if not ideal

4/ Redmine is a pretty big Rails app ; it doesn't use a lot of gems so many things are done manually, which is a maintenance burden but somehow also a safe choice in the ruby world : cool gems change every 6 months and we don't have the workforce for adapting the underlying code base each week a new cool gem replaces the "so last week" old gem

5/ If you want to document things I think I can help: every bit of clear inline documentation provided as a patch in a dedicated issue can be integrated easily. So if you want to work on that, your help is very welcome, and I can review things or even discuss things with you by email if needed

Hope it clarifies things a bit, let me know what you think

Also, I didn't mention one key reason why documentation can be lacking: there's a strong focus on documenting things for lambda users. Just see the official Guide, it includes a lot of documentation about features, concepts, how to achieve things with Redmine. And our time is limited so, maybe technical documentation suffers a bit from that (but as a sysadmin by trade, I can say that Redmine is clearly better documented than 95% projects I see every day...).

Thank you for replying Jean-Baptiste. I appreciate it.

I can completely understand the focus on users for documentation. To me that makes complete sense. As someone working in an IT department with a small staff, I can, and do, completely agree with your comment that Redmine is better documented than most projects (though it may be worth noting that most projects are not as huge as Redmine).

I'm going to reply to the rest of your post in points as I suspect my reply will be easier to follow that way:

1/ I can understand a small team size. I often run into this problem where I work (I am the only developer and the only dedicated IT staff member). I completely understand that with a small team and not a lot of time, one of the first things that suffers is documentation.

2/ I would absolutely love to see more documentation on plugin creation. I currently tend to avoid making plugins for Redmine like the plague because it is so difficult to figure out how to do what I need to do. Often times I find myself just making things on my own as standalone applications and using iframes to include them, something I'm not terribly proud of doing.

I didn't realize the REST API was working at this point? Most of what I see on the forums (granted I mostly Google to find things relating to plugin creation, and therefore only stumble upon the REST stuff by accident) seems to point to them not being done yet? Either way, I'm glad that is a priority for documentation as well.

3/ As someone who doesn't know Rails conventions terribly well, they don't prove very useful for me to begin to understand how Redmine is put together. I can usually find the files I am looking for (having worked with RAILs and other frameworks enough to know how they are arranged), but often times finding the method I am looking for or determining the flow that lead to it, proves to be a very difficult and time consuming process for me.

Inline documentation doesn't take too long to write. And documentation better than the 13 (2 of which are actually TODOs) lines in app/controllers/projects_controller.rb, would be fantastic. As someone who is still learning Ruby and Rails it is hard to follow. Even if I was an experienced Rails coder, it would be much faster to read comments to determine what is going on than having to parse code in my head. A quick explanation of what each not completely trivial method does above said method would also be fantastic.

4/ That is understandable.

5/ I will definitely do that. If I manage to struggle out how something works and document it, I have absolutely no problem sharing that with everyone else. I was actually thinking of putting together a website to do just that (along with instructions on how to do things that I have struggled to work out), but if you guys are willing to take patches, that would work too. Likewise I should probably make pages on your Wiki when I manage to work out how to do things.

Again I apologise for my rudeness in the first two posts. Whenever my boss asks me to make changes to our Redmine installation it usually frustrates me almost to the point of tears.

I come from the world of PHP. I learned that from modifying phpBB and reading the PHP manual pretty much from cover to cover. These days I do a fair amount of extension writing for Mediawiki (which is one of the best documented pieces of software I have seen) along with writing my own software. Coming over to Ruby and Rails has been a bit of a rough task for me (conventions are so entirely different for one). Adding the documentation levels of Redmine (or lack thereof) to that has been especially hard.

Thank you again for your reply and your understanding.

I realize I didn't finish my point "4" : the argument I wanted to make is that Redmine is a pretty big rails app and not the best fit if you want to learn how Rails works in general. The fact that things are made manually in Redmine implies here and there that things are melt together and not extracted as cleanly as they would if they were standalone gems used by multiple projects (which 1/ can lead to a lot of complexity, see Devise or Omniauth for instance, 2/ has been somehow done in the past for some models features, see "lib/plugins/").

Your first post left me with the impression you wanted to take Redmine as a starting point to learn Rails (which I did in some ways 5 years ago, but the codebase was a lot simpler at the time, and I think watching all railscasts helped me more than reading Redmine source code).

From your last reply I understand that Redmine is already a tool of choice where you work and you need to patch it / change its behaviour, that's a little different. I do this job daily too for nearly 5 years (not my main task, but still). So as long as your questions don't involve integration with 3rd party softwares, I'd be really happy to help and explain the best approaches I know.

I think the best thing would be to document things here in the wiki as long as it's purely documentation. I reserved a "redmineplugins.org" domain long ago if we have other purposes (build an open CI server for redmine plugins for instance, or distribute screencasts) but never had the time to launch that..

Please don't hesitate to file new posts (here on the forum, it's fine ; one message per topic ok ?) and ping me via email or twitter if I don't answer in the following week.

Oh and as far as the REST API is concerned, it's definitely considered usable and stable for a while now. Pretty much all iOS / Android apps out there rely on it for interacting with Redmine. The Rest_Api page lists the exact status of each part of the API. Main ones (Issues, Projects, Users) are stable and proved to be solid in the past versions. Newer ones may change in the future but should be usable. In any case, it's better to have some sort of automated tests when you develop that kind of things : it allows you to upgrade your Redmine without any fear of breaking silently your 3rd party integration...