Developer Documentation

Added by Derric Atzrott over 4 years ago

Is anyone working on, or planning to work on getting Redmine documented?

I'm looking for something similar to what Mediawiki has here: https://www.mediawiki.org/wiki/Developer_hub

They have documentation of every single class, almost every method in those classes, their entire plug-in architecture, and their API.

Is there anything like that in the works at all, or is anyone planning on putting something like together, or any sort of actual documentation at all? Even inline comments in the code for Redmine would be awesome. Most of the controllers only have a line or two of comments if that.

In the past when I have asked questions here or come to look something up, I am often pointed towards "Look at how other Plugins do it," or "Open up this file and take a look at how the code works." I've been trying to make use of modifying Redmine as a way to teach myself about Ruby and Rails, but it is proving rather difficult to manage.

I apologise if I come off rude at all. This is not my intent; I'm just sort of frustrated. If I knew more Ruby I would offer to help document the code myself even.

I would point towards Mediawiki as my standard for what documented code should look like.

Replies (6)

RE: Developer Documentation - Added by Derric Atzrott over 4 years ago

I'm going to take this as a no.

RE: Developer Documentation - Added by Jean-Baptiste Barth over 4 years ago

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

2/ From a developer point of view, the documentation is not exhaustive at all, but there are some pages here: Developer_Guide. There are two things the core contributors aims at improving I think:
  • 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)
3/ There's not much documentation on the core itself. Two reasons about that:
  • 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

RE: Developer Documentation - Added by Jean-Baptiste Barth over 4 years ago

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

RE: Developer Documentation - Added by Derric Atzrott over 4 years ago

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.

RE: Developer Documentation - Added by Jean-Baptiste Barth over 4 years ago

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.

RE: Developer Documentation - Added by Jean-Baptiste Barth over 4 years ago

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

(1-6/6)