[ANN] Documentation and Requirements via Confluence

[Andreas Pieber]

Hey Guys,

For some days now we've a confluence instance up [1]. Christoph and I have started to give it a shot, add some base content and set up a base infrastructure. Now we're coming to you interesting about your ideas and what you think about it. First of all some basics:

it's only required to create either a confluence OR a jira account. Independently where you create it it's valid for both instances; If you're a jira administrator you're also a confluence administrator (and the other way round).

Now, there are some thoughts behind the setup of the confluence

a) documentation is a pain in the ass in docbook. Most developers are not comfortable with docbook AND our tooling chain isn't making it any easier

b) requirement gathering in jira is a pain. Jira epic issues are simply not a place to write quite long discriptions of a feature (even containing images, UI mocks and long descriptions) into a single issue. Instead confluence offers a great place for this

c) use case gathering in jira is a pain. We've quite a ton of use cases from various users and ppl we talk to. Such use cases could be new requirements, many issues or simply there for reevaluation from time to time. Currently we do not raelly have any place to store those

d) No place to store misc documents, discussions, demos, ... In fact we have no real place to store misc documents right now. e.g. protocols for our meetings, or presentations we're doing about the oeb, ... maybe some parts could be stored on the homepage, but not all of them and also...

e) the homepage is quite a pain to get used to. First of all, again a new language to learn which makes the change pretty hard.

Seeing all those problems Christoph and I hacked out some kind of plan. First of all we've added four spaces:

1) Homepage

2) Documentation

3) Requirements & Ideas

4) Evaluations & Architecture Decisions

5) Miscellaneous

1 - Homepage

The homepage space is dedicated for all information many ppl might want to change but which is NOT part of the documentation. E.g. our infrastructure (mailinglists, irc, ...), sponsors, team members, ... All not so fancy parts of the homepage which might change from time to time and which could be included into the homepage via an iframe; this does also include a complete redesign of the homepage. All information currently on the homepage is either crap or not really useful. The idea is to build an eyecatcher completely based on css/html/js which basically does not need any changes.

2 - Documentation

The documentation will look a little bit different from now. There are still not all points closed, but basically we've tough of something like the following: We'll document everything from the version point of view of the OpenEngSB distribution. That way we can (at least theoretically) release a new version every time we release a sub module. In addition we can version and pack the entire documentation from one point of view together to one big document. Besides the documentation is still available online, searchable and even found by google. This should make things ways easier. Compared to the homepage, where we'll need to do a big-all-at-once switch, the documentation can be taken over step by step and where required. This is possible for the main reason that the current documentation is anyhow near to useless.

3 - Requirements & Ideas

This space is intended as our new "Epic" repository. Although we've tried JIRA is NOT a good place to discuss and iron out ideas before breaking it down to sub issues. The idea is that we add architectural descriptions about all parts not implemented by now for the OpenEngSB in this space and link issues to it afterwards. This should make the game ways easier for us.

4 - Evaluations & Architecture Decisions

We've discovered for some time now the problem that we've executed an architectural decision, but weren't able afterwards to recall why we've done something in a specific way. This is similar to comparisons we've done to potentially similar software. Nobody can remember what we've discovered/decided then. This space is wholly dedicated for storing up such discussions and reports.

5 - Misc

The misc space is dedicated to everything not belonging to any of the other spaces. Examples are meeting prototcols, small examples, and who knows what else will end here...

-- Blogs

In confluence you can add blog entries to every space. We will add entries about new releases, new examples, important documentation updates, ... All those entries could be done directly at the relevant news page. The blogs will be aggregated by confluence and we'll show them in a news section on our new homepage. In addition everyone interested into the project can also register there.

We would really like to know what you think about the new model. We believe that, since most of the public parts are in quite a devastating state by now anyhow (and need a major rework) it's not much more work than it would have been otherwise.

Kind regards,

Andreas

[1] http://requirements.openengsb.org