Discussion:
Miranda Core Documentation
Nisses Insane
2008-06-07 15:16:18 UTC
Permalink
Hi!

I was browsing Miranda forum and Miranda core and plugin sources for
the whole day (and night). One question bothers me much. Is there any official
document (specification) other than Plugin Development Guide (4 pages)
and 4 html pages Services & Hooks Overview both dated year 2006? Or
it's just several developers with an idea in their minds but not on
paper? I've seen many plugins going in different directions
(sometimes opposite ones) and many changes (mostly in plugins) that
plenty of developers call unreasonable and thoughtless. Is this the
maintained project or every developer should do what he wants to
(like the service plugins becoming more important than core)? Is
there no directions and roadmap?

The project was great, great and glorious! ...back in 2006. Now it's
more like a mess, still precious but falling into chaos, more
visibly after failed attempt to implement UUIDs (athough it was planned
the people got surprised).

The project documentation is... missing?

I hope I'm wrong and someone points me to some resources filling
missing information. There's another project Pidgin (former GAIM)
which seems to be more organized and worth following from the side
of docs and planning.
--
Best regards,
Nisses mailto:miranda-***@public.gmane.org


-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
Adam Strzelecki
2008-06-08 16:41:16 UTC
Permalink
Post by Nisses Insane
I was browsing Miranda forum and Miranda core and plugin sources for
the whole day (and night). One question bothers me much. Is there any official
document (specification) other than Plugin Development Guide (4 pages)
and 4 html pages Services & Hooks Overview both dated year 2006? Or
it's just several developers with an idea in their minds but not on
paper?
IMHO miranda/includes/*.h is now the best specification, but indeed we
miss some DoxyGen or RDoc documentation.
I remember my first steps programming Miranda were really hard, so I
understand new developers being discouraged by the lack of the
guidelines.
Post by Nisses Insane
I've seen many plugins going in different directions
(sometimes opposite ones) and many changes (mostly in plugins) that
plenty of developers call unreasonable and thoughtless. Is this the
maintained project or every developer should do what he wants to
(like the service plugins becoming more important than core)? Is
there no directions and roadmap?
I doubt there's one recent, there was lot of discussion about
Miranda's future last year, we had miranda-internal very active, now
it's kind of dead.
Koobs there's was trying to put the project in the right direction,
but it seems we missed final consensus.
Post by Nisses Insane
The project was great, great and glorious! ...back in 2006. Now it's
more like a mess, still precious but falling into chaos, more
visibly after failed attempt to implement UUIDs (athough it was planned
the people got surprised).
I don't want to start flame war here, but I share the same feeling.
Miranda is not recent project though, it had many developers, may
ideas. I perceive current situation as natural process for many
projects, Miranda had its days of fame already. Now the newer projects
having fresher ideas are about to take over the lead.
Moreover openness of Miranda API, many plugins doomed Miranda to
chaos. I have nothing against the plugins, but the core should be kept
crystal clear, but it's not.
For example there're 3 forks of clist sharing 60% of same source-code
base, so don't look for DRY in the M's code.
Post by Nisses Insane
I hope I'm wrong and someone points me to some resources filling
missing information. There's another project Pidgin (former GAIM)
which seems to be more organized and worth following from the side
of docs and planning.
Pidgin is amazing example of revitalization. Currently I'm little bit
supporting Pidgin sending them patches as now I'm one of happy Adium
(sharing same proto lib) users.
The Pidgin developers community seems to be very active at the moment,
also Pidgin is multiplatform IM so that's great advantage.

Finally I think there's still a chance for Miranda, only if there was
someone who could cut the bloat off the core.

Regards,
--
Adam Strzelecki |: nanoant.com :|


-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
Kubilay Kocak
2008-06-14 00:38:14 UTC
Permalink
Nisses,

I appreciate you taking the time to share your thoughts. I must start with
saying your feelings are echoed by quite a few developers, both internal and
external to the core team, as well as many of our users. I hope the
following goes a long way to giving you, and others the information they
need.

The issues I see from my perspective are many, but I will try to summarise
them as best I can. Keep in mind they are from my experience and opinion
only:

a) Timing. We've had a tough few years, with the project recovering from the
loss of a large proportion its core team in the not so distant past. A
generous few donated their hard earned time to keeping the project alive for
quite some time. Focusing on attracting developers and contributors to the
project without fracturing the culture and strategy is something we are
still learning to do. Quite a few ideas have been put onto the table on how
to achieve this, but we need to make this a priority, document what we
expect from people, and do it.

b) Consensus. There is quite a lot of talk about what needs doing, how we
should be doing it, and not much doing. I am guilty of this myself, and I
will go into detail in subsequent points. This is not so much from actual
coding point of view, but rather around the supporting systems and processes
around which a healthy community thrives. Consensus has been relatively
difficult to achieve as Adam has mentioned.

c) Common-ground. As the project maintainer, it has been difficult for me to
find common ground and mutual understanding with our developers about the
finer points of non-code specifics that we need to see addressed in the long
term. Documentation, usability and testing are vitaly important, but
nonetheless often not seen as first-class citizens when compared to new
features, ie: the "fun stuff".

I am by no means passing the blame onto our developers, they do an amazing
job with the resources they have, but as a team, what we have is not good
enough.

The main cause of this in my opinion, is the fact that I don't (yet)
contribute code to the project and prefer to focus on the non-technical
aspects of the project. As a consequence, I have to find ways to develop
respect and mutual understanding in not so intuitive ways.

d) Culture. We have extremely talented people working on our team, and we
all have ego's, myself included. Signs of territoriality and ownership are
destructive and need to be addressed. Further, there has always been the
tendency to keep 'core discussions' internal, without transparency or
involving the community.

My opinion is that this has been due to the desire to avoid never-ending
discussions and negative feedback, has been common in the past, and which I
feel is a natural human tendency. It is not an ideal situation, has many
disadvantages, is not a suitable way to be engaging our community, and is
one the first things that needs to change.

e) Limited Resources. We have people donating their time and effort and
money to the project. This is not designed to be an excuse and should play a
relatively small part in the successful evolution of Miranda, given that
many Open-Source project have proven successful with the same constraints.
It is to serve as a reminder that priorities and expectations need to be
managed accordingly.

f) Motivation and Momentum. Progress encourages motivation and stumbling
discourages it. Mainly due to the contributing factors I mention above,
gaining momentum has been awkward and difficult at best, nonexistent at
worst. Overcoming the lack of momentum requires seperating large, undefined
and non-tangible issues into bite size peices and easy-to-achieve goals.

The short summary of the point I ouline above is, we are a successful
project with extremely talented people contributing to it. We have a
community that cares a great deal where Miranda IM goes, and we as a project
team need to reduce the barrier-to-entry to leverage it to everyones our
benefit.

I welcome any discussions, suggestions and help in addressing the issues ive
mentioned.
Post by Adam Strzelecki
Post by Nisses Insane
I was browsing Miranda forum and Miranda core and plugin sources for
the whole day (and night). One question bothers me much. Is there any official
document (specification) other than Plugin Development Guide (4 pages)
and 4 html pages Services & Hooks Overview both dated year 2006? Or
it's just several developers with an idea in their minds but not on
paper?
IMHO miranda/includes/*.h is now the best specification, but indeed we
miss some DoxyGen or RDoc documentation.
I remember my first steps programming Miranda were really hard, so I
understand new developers being discouraged by the lack of the
guidelines.
Post by Nisses Insane
I've seen many plugins going in different directions
(sometimes opposite ones) and many changes (mostly in plugins) that
plenty of developers call unreasonable and thoughtless. Is this the
maintained project or every developer should do what he wants to
(like the service plugins becoming more important than core)? Is
there no directions and roadmap?
I doubt there's one recent, there was lot of discussion about
Miranda's future last year, we had miranda-internal very active, now
it's kind of dead.
Koobs there's was trying to put the project in the right direction,
but it seems we missed final consensus.
Post by Nisses Insane
The project was great, great and glorious! ...back in 2006. Now it's
more like a mess, still precious but falling into chaos, more
visibly after failed attempt to implement UUIDs (athough it was planned
the people got surprised).
I don't want to start flame war here, but I share the same feeling.
Miranda is not recent project though, it had many developers, may
ideas. I perceive current situation as natural process for many
projects, Miranda had its days of fame already. Now the newer projects
having fresher ideas are about to take over the lead.
Moreover openness of Miranda API, many plugins doomed Miranda to
chaos. I have nothing against the plugins, but the core should be kept
crystal clear, but it's not.
For example there're 3 forks of clist sharing 60% of same source-code
base, so don't look for DRY in the M's code.
Post by Nisses Insane
I hope I'm wrong and someone points me to some resources filling
missing information. There's another project Pidgin (former GAIM)
which seems to be more organized and worth following from the side
of docs and planning.
Pidgin is amazing example of revitalization. Currently I'm little bit
supporting Pidgin sending them patches as now I'm one of happy Adium
(sharing same proto lib) users.
The Pidgin developers community seems to be very active at the moment,
also Pidgin is multiplatform IM so that's great advantage.
Finally I think there's still a chance for Miranda, only if there was
someone who could cut the bloat off the core.
Regards,
--
Adam Strzelecki |: nanoant.com :|
-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Miranda-Develop mailing list
https://lists.sourceforge.net/lists/listinfo/miranda-develop
--
--
My reality check just bounced.
Piotr Piastucki
2008-06-14 08:55:49 UTC
Permalink
Hi,

I must admit that I agree with Kubilay in all the points he mentioned.
It looks like my feelings about the project are pretty much the same.
There are a couple of things I would like to add:
1) as a developer (and Miranda user) I really miss any development
roadmap. I have almost no idea where the project goes currently and most
of my knowledge is based only on the SVN commit logs. We cannot achieve
too much without a clear plan of what we actually want to achieve :)
2) usability - Miranda definitely needs a good graphical designer who
can make it look both modern and simple if we want to attract more
users. Most people cannot afford spending a couple of hours (days?)
setting up their IM client.

Cheers,
Piotr



-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
Kubilay Kocak
2008-06-14 09:15:26 UTC
Permalink
I can't agree with you more Piotr, and I actually felt slightly guilty for
not leaving my previous post on a lighter note, and perhaps also for not
being more positive.

A roadmap is a great thing, but one needs to remember that a roadmap is
nothing without a good degree of consensus. Making sure that people are
given ample opportunity to provide input, understand their responsibilities,
and are generally 'on the same wavelength' is vital before you can even
consider looking to the future.

Also consider that a roadmap must align itself with goals, otherwise it's
just a blindmap that noone feels accountable to. This is where culture comes
into play, and why 'it' needs to be addressed before anything. Who are we?
What do we stand for? What do we want from the project?

Forget the .exe's and dll's that come with our releases for a moment. They
are symptoms of the culture.
Post by Piotr Piastucki
Hi,
I must admit that I agree with Kubilay in all the points he mentioned.
It looks like my feelings about the project are pretty much the same.
1) as a developer (and Miranda user) I really miss any development
roadmap. I have almost no idea where the project goes currently and most
of my knowledge is based only on the SVN commit logs. We cannot achieve
too much without a clear plan of what we actually want to achieve :)
2) usability - Miranda definitely needs a good graphical designer who
can make it look both modern and simple if we want to attract more
users. Most people cannot afford spending a couple of hours (days?)
setting up their IM client.
Cheers,
Piotr
-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Miranda-Develop mailing list
https://lists.sourceforge.net/lists/listinfo/miranda-develop
--
--
My reality check just bounced.
Piotr Piastucki
2008-06-14 09:51:43 UTC
Permalink
Kubilay,

Apparently you did not get my point or I did not make myself clear
enough. A roadmap for me means a set of goals we want to achieve and it
should always be a result of consensus between all people involved
(developers, users etc.) otherwise it is worthless as you said.

Cheers,
Piotr
Post by Kubilay Kocak
I can't agree with you more Piotr, and I actually felt slightly guilty
for not leaving my previous post on a lighter note, and perhaps also for
not being more positive.
A roadmap is a great thing, but one needs to remember that a roadmap is
nothing without a good degree of consensus. Making sure that people are
given ample opportunity to provide input, understand their
responsibilities, and are generally 'on the same wavelength' is vital
before you can even consider looking to the future.
-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
Kubilay Kocak
2008-06-14 10:20:29 UTC
Permalink
We're talking about different levels of the same thing. Perhaps I should
clarify my definition of roadmap :)

A roadmap from a strictly project management point of view is a set of tasks
or 'todo list' items that revolve around higher-levels and longer term
'goals'.

For example, the 'goal' of Usability must be broken down into 'roadmap
items' that cumulatively work towards and contribute to achieving the
'goal'.

Boris also makes an important point, you also need to weigh the roadmap
items again available resources.

Without goals, roadmap items have no direction, and without resources to
deliver roadmap items, a todo list is useless.

The way I'd like to address this particular problem is by first creating a
very short list of 'high level goals', similar to our familiar 'smaller,
faster, easier' mantra, but with clearer definition, and needs to involve
everyone, even if it does sound a little corny. A mission statement if you'd
like to call it that.

Regards,

Koobs
Post by Piotr Piastucki
Kubilay,
Apparently you did not get my point or I did not make myself clear
enough. A roadmap for me means a set of goals we want to achieve and it
should always be a result of consensus between all people involved
(developers, users etc.) otherwise it is worthless as you said.
Cheers,
Piotr
Post by Kubilay Kocak
I can't agree with you more Piotr, and I actually felt slightly guilty
for not leaving my previous post on a lighter note, and perhaps also for
not being more positive.
A roadmap is a great thing, but one needs to remember that a roadmap is
nothing without a good degree of consensus. Making sure that people are
given ample opportunity to provide input, understand their
responsibilities, and are generally 'on the same wavelength' is vital
before you can even consider looking to the future.
-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Miranda-Develop mailing list
https://lists.sourceforge.net/lists/listinfo/miranda-develop
--
--
My reality check just bounced.
Nisses Insane
2008-06-19 16:55:23 UTC
Permalink
Hello Kubilay,

The roadmap shows everyone where the project is heading. It is a very good and important thing. But you also need to establish procedures of doing things. Many little projects grow bigger and die because of bad organization. Project documentation is fundamental for big projects. It shows how existing things are done and how future development should look like (standards, specifications). Many developers just don't bother reading whole sources just to get an idea how things were done. It is a waste of time. Time that could be used for development and not for reinventing the wheel. You need to have a roadmap but you also need the rules of the road you are driving. Efficient ways are needed because no one likes to waste his time.
--
Best regards,
Nisses mailto:miranda-***@public.gmane.org


-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
Kubilay Kocak
2008-06-20 04:20:56 UTC
Permalink
Nisses,

Your rationale is exactly why I decided to join the project a few years ago.
What I wanted to highlight in my original reply were the issues that have
been and continue to be hurdles to the ideas we both share.

Back onto the subject of API Documentation, I have spent a little time over
the last few days playing with Doxygen, with a view to getting at least
basic API information out to the public, while our team works to augment the
sources with doxygen specific comment blocks.

It will be available at http://www.glit.ch/miranda/doxygen/html/ until the
developers and I are happy with how useful it is, at which point we will be
making the resource available from the Development pages of our main site.
I'd like to eventually get doxygen automated to the extent that it will
document sources exported straight from our SVN repository, and building on
a regular basis.

I hope this proves useful to you in the meantime. If you have any
suggestions on doxygen specific tweaks, don't hesitate to let me know.

Koobs
Post by Nisses Insane
Hello Kubilay,
The roadmap shows everyone where the project is heading. It is a very good
and important thing. But you also need to establish procedures of doing
things. Many little projects grow bigger and die because of bad
organization. Project documentation is fundamental for big projects. It
shows how existing things are done and how future development should look
like (standards, specifications). Many developers just don't bother reading
whole sources just to get an idea how things were done. It is a waste of
time. Time that could be used for development and not for reinventing the
wheel. You need to have a roadmap but you also need the rules of the road
you are driving. Efficient ways are needed because no one likes to waste his
time.
--
Best regards,
-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
_______________________________________________
Miranda-Develop mailing list
https://lists.sourceforge.net/lists/listinfo/miranda-develop
--
--
My reality check just bounced.
Scott Ellis
2008-06-20 06:22:00 UTC
Permalink
A most excellent response to a valid criticism. Congrats - that's one reason
(among many) why Miranda still has a bright future.

Boris Krasnovskiy
2008-06-14 10:11:09 UTC
Permalink
Hi Piotr,

The list of things we need to achieve is known for few years. The question
is what developers willing to donate there time towards.
Most of people here agree that certain features are useful and needed, but
when it the time to take time away from family, friends, vacation, whatever
else and work on them, they disagree too do that, as they do not consider it
wise use of their personal for features they do not personally need or any
other reason. So what good is that roadmaps, consensus of users, etc., if
there is nobody to do the work.

-----Original Message-----
From: miranda-develop-bounces-5NWGOfrQmneRv+***@public.gmane.org
[mailto:miranda-develop-bounces-5NWGOfrQmneRv+***@public.gmane.org] On Behalf Of Piotr
Piastucki
Sent: Saturday, June 14, 2008 3:56 AM
To: miranda-develop-5NWGOfrQmneRv+***@public.gmane.org
Subject: Re: [Miranda-Develop] Miranda Core Documentation

Hi,

I must admit that I agree with Kubilay in all the points he mentioned.
It looks like my feelings about the project are pretty much the same.
There are a couple of things I would like to add:
1) as a developer (and Miranda user) I really miss any development roadmap.
I have almost no idea where the project goes currently and most of my
knowledge is based only on the SVN commit logs. We cannot achieve too much
without a clear plan of what we actually want to achieve :)
2) usability - Miranda definitely needs a good graphical designer who can
make it look both modern and simple if we want to attract more users. Most
people cannot afford spending a couple of hours (days?) setting up their IM
client.

Cheers,
Piotr


-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://sourceforge.net/services/buy/index.php
Loading...