I create a new thread because this is not related to the original "Why Java got popular" thread...

2012/2/28 Everton Vieira

Ok, we need more concrete plans. I promise to look carefully the issues of project management if you have good ideas.
Do you mean that the core team should divide the tasks for contributors? Please explain more.

Improving the documentation is now a "hot topic". I think more people should get write access to the doc directory in the repository, if only there are people willing to take the effort.

While improving project management is a good idea, I still strongly feel that most of criticism is not fair or truthful. In fact all questions are answered in mailing list and forum, IMO better than with many other open source projects.
The classic whining about the revision control and bug tracking is quite nonsense. It is typically from people who have never contributed code for the project.

Still, I will have an open mind for ideas of better project management.

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/3f86c22f/attachment.html>

The bug tracker works perfectly for the bugs, i would only suggest to make a front-end in the IDE in order to make him more visible, or at least by start a simple link in the help menu of the IDE would be enough. This is a patch so small and simple that i'm even with shame to do it :p.

2012/2/28 Juha Manninen

As a newcomer I would like to see on the web site a team organization chart. The current contributors would appear in the roles they currently play. Open positions would be identified with links to pages where you can find out more about what is involved in those positions.

Also included would be people who regularly contribute to the mailing lists and a short description about who they are, where they live, etc.

All this enables people to get the "lay of the land". It really helps you establish a context when you read someone's message on a mailing list to go see what their role is in the project.

These are not project management ideas such as how to better manage the activity of the project. They are project management ideas to help organize the material of the project so it is more transparent - what is happening and who is doing what. It is important because as a newcomer you need to get a good sense of this before you can figure out where you want to plug yourself in.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/a061a7e6/attachment.html>

It is probably not very up to date ...
http://wiki.lazarus.freepascal.org/Developer_pages

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/1a7bcb8e/attachment.html>

About the documentation i had the idea of make centralized data help that could generate the off-line as well the on-line help versions. And to elegantly show the contributor who did the examples and so on.

2012/2/28 Juha Manninen

2012/2/28 Everton Vieira

It is already there for a long time: Help -> Reporting a Bug

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/17a7da37/attachment.html>

Another idea is for someone to summarize a lengthy exchange in a mailing list. The summary would be something along the lines of: "The idea of X has been brought up and appear to be 3
options for moving forward. A would be least disruptive. B would take the most work but would produce the ideal result. C would be an alternative to B but would take the project in a whole new direction. The core team would like to pursue B but needs Y or Z to be done first. Anyone who wants to pursue C should know their efforts will be difficult to integrate in the future. See the following wiki page for our current plans in this area."

A summary like to would certainly help me understand where we are on the documentation issues that have been discussed in the past week or so.

The value of it is in helping everyone understand that the core team is paying attention to the issues that are brought up and that steady progress is being made (even if it only discussing an issue and placing it properly in the context of the developmental plan).

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/dab93cd2/attachment.html>

About the project management is something like the bug tracker but not for bugs. With all that richness that has a project management: projects, teams, head members, status of it, code already done, code to be done, ideas about it, discussions on, notes from everyone, and so on.

2012/2/28 Juha Manninen

Op 28 februari 2012 21:01 heeft Everton Vieira
het volgende geschreven:

The bug tracker works perfectly for the bugs, i would only suggest to make a front-end in the IDE in order to make him more visible, or at least by start a simple link in?the help menu of the IDE would be enough. This is a patch so small and simple that?i'm even with shame to do it :p.

I am a long time user of Lazarus, so a lot of things are obvious for me, Other things are not, because I cannot look at it with fresh eyes anymore.

A simple link in the menu: Help -> Reporting a bug.

What more is needed?

Vincent

2012/2/28 Juha Manninen

Is true, my fall, but the idea of the front-end is still up.

2012/2/28 Everton Vieira

It is already there for a long time: Help -> Reporting a Bug > Is true, my fall, but the idea of the front-end is still up.

You can perhaps make such front-end yourself as a contribution. :) It is not a trivial task because you must connect and update the actual Mantis bug tracker and mostly replicate its user interface. It makes sense if the IDE can automatically collect information about an exception or other error, and about the environment like OS, FPC version, Lazarus version etc. Otherwise it does not make much sense to replicate it.

BTW, this is not really an issue of project management but rather bug management.

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/e3d76148/attachment.html>

2012/2/28 Juha Manninen

We can always starts small, makes more sense starts small. But, by now, i don't have a clue about how to start such front-end.

Improving the documentation is now a "hot topic". I think more people should get write access to the doc directory in the repository, if only there are people willing to take the effort.

IMO this is not a good idea, for several reasons:

I already removed so much crap from the docs, which may creap in again with uncontrolled access.

In contrast to source code, there is no compiler that could verify the correctness of the documentation. Most entries deserve notes like "deserves citations" in wikipedia, and background information proofing the descriptions as correct. The new <notes> could be used to supply such information, similar to the "discussion" page in wikipedia.

The XML files are very sensitive to reformatting or moving parts around. Reformatting done e.g. by LazDE can result in an commit of the entire file, hiding the essential differences.

DoDi

About the documentation i had the idea of make centralized data help that could generate the off-line as well the on-line help versions.

What's missing from the current documentation tools?

And to elegantly show the contributor who did the examples and so on.

Right, sometimes it would be nice to know whom to ask specific questions.

DoDi

2012/2/28 Everton Vieira

This was the best idea so far. I think there is open source project management programs available. However there is a big difference between professionally run SW projects and hobby open source projects:

Professional projects in a company environment have a known number of developers who all will work a known period of time every day. If you can estimate how many man-hours a certain task will take then you can divide the tasks and estimate the whole project's development time.

In a hobby project things are different. Nobody can promise exact number of hours to work on the project. Also, developers often do what they want based on personal preferences, not following some project manager's orders. This actually makes it fun to work in an open source project. Everton, did you consider these things in your suggestion?

It would be mostly a ToDo list with task assignments and maybe time estimates. In fact the wiki already has such info although it is outdated.

I am still thinking, do you need the project management data for getting a suitable task for yourself, or is it more like "nice to know"? It may also be an illusion from your side that contributing code to a big project becomes easy if only there was a project manager with a nice list of tasks.
No, you will have to browse and study the existing code for hours and hours before you start to understand it enough to make intelligent changes. When you do it, other developers will be very helpful through the mailing list, I promise. Now you clearly have not even looked at the code.

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/c1322d2b/attachment.html>

As much as I would like to get answers directly (and promptly) from the source experts, I would prefer that the developers be allowed to focus on development (if that is their passion). I would rather have a set of SMEs (subject matter experts) as a buffer. Yes, they will have to ask the developers questions, but they can act as intelligent filters and translators (meanings of questions, not language). This would also help develop the next set of developers or documentation writers, as they will develop systems to help the inexperienced help themselves. -------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/7c8e677c/attachment.html>

2012/2/28 Everton Vieira

About the documentation i had the idea of make centralized data help that could generate the off-line as well the on-line help versions. And to elegantly show the contributor who did the examples and so on.

Again, you clearly have not studied the existing ?

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/47ec97bb/attachment.html>

Juha Manninen wrote

2012/2/28 Everton Vieira About the documentation i had the idea of make centralized data help that could generate the off-line as well the on-line help versions. And to elegantly show the contributor who did the examples and so on. Again, you clearly have not studied the existing ?

If it is already been done, then sorry, and please, disregard this mail.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/299477dc/attachment.html>

2012/2/28 Rich Saunders

Rich, who would make that summary? I hope you don't mean the core developers would have to make it, in addition of using all their available time creating code and documentation.
A right attitude from you would be to offer yourself to make such summary.

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/9d21c6da/attachment.html>

2012/2/29 John Repucci

Uhhh, this was another out-of-reality comment. So, can you please name the set of SMEs. You are one of them obviously, but who are the others?

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/a2b875f9/attachment.html>

I think can be adapted.

It would be mostly a ToDo list with task assignments and maybe time estimates. In fact the wiki already has such info although it is outdated. I am still thinking, do you need the project management data for getting a suitable task for yourself, or is it more like "nice to know"?

I think would be better for everyone.

It may also be an illusion from your side that contributing code to a big project becomes easy if only there was a project manager with a nice list of tasks.

I think it would be easy with more info about it.

No, you will have to browse and study the existing code for hours and hours before you start to understand it enough to make intelligent changes.

I think it would be easy with more info about it.

When you do it, other developers will be very helpful through the mailing list, I promise. Now you clearly have not even looked at the code.

I`ve looked yes, some of it, not all for sure, but i do not see how this make any difference on this subject.

Juha

But, of course, if you don`t think is a good idea, then ok.

Sure i`m not here to convince anybody of nothing. I`m only proposing ideas. Only that. Sure if this ideas don`t found resonance i would be the last to try to convince anybody. I simply don`t have the energy to do this struggling.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/7358fd3c/attachment-0001.html>

Of course, the core developers would not be expected to do it unless they chose to. I see it as a project management task.

A right attitude from you would be to offer yourself to make such summary.

I'm considering it. If productive exchanges like this project management thread continue I might just start doing it. We'll see how it goes.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/d1cd6464/attachment.html>

As much as I would like to get answers directly (and promptly) from the source experts, I would prefer that the developers be allowed to focus on development (if that is their passion).

In a perfect world the specificiation preceeds the implementation :-]

What's so hard with documenting a new feature *together* with the implementation? It must not be a perfect documentation, but at least the essential facts can be added to every new identifier, using the FPDoc Editor.

DoDi

You designate SME's as part of the team. You list them in the team organization chart. You initially mark each role as vacant.

If you describe the job well people will volunteer, especially if someone is identified as a coach. Something like "We need people to intermediate between core developers and users who report trouble or ask for enhancements. We call these people SME's. You watch for messages in the mailing lists and reports in the tracker and make sure they are clear. Sometimes you may need to reproduce a problem. Sometimes you may need to clean up the language used to report the issue. (Much of this can be done directly with the original poster so as to not clutter up the public forums.) When you think it is a real concern, clearly identified, and reproducible, send it on to the core team. Of course you only need to do this for items that relate to the area for which you have volunteered."

By the way, I would NOT call the subject matter experts. I would just call them subject matter volunteer coordinators.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/e1d012cf/attachment.html>

2012/2/29 Rich Saunders

Of course, the core developers would not be expected to do it unless they chose to. I see it as a project management task.

Who is the project manager then? I have tried to explain in my mails that you guys don't understand the reality here.
This project does not have a project manager like some commercially backed projects have (they have also paid programmers).
This one has a relatively small group of voluntary developers. The "organization" is very flat and flexible.

A right attitude from you would be to offer yourself to make such summary.

I'm considering it. If productive exchanges like this project management thread continue I might just start doing it. We'll see how it goes.

The most productive exchanges are the actual code or documentation contributions.
If you are asking for a permission to make such summary then yes, please, go ahead. You don't need to ask permission really. You can place them in wiki for example.
If you are asking for recognition then yes, your work will be much appreciated.
Well, I would like some recognition, too. I have used so much time coding Lazarus that in fact my school studies are suffering from it. Other developers have used still more time.

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/771c93e9/attachment.html>

Everyone understands that part of reality. It has been repeated many times.

However, this is the reality that I'm trying you to understand: You need better project management! Maybe not a "project manager" but somehow project management should be be paid more attention than it has been. I thought you understood that back when you posted "I promise to look carefully the issues of project management if you have good ideas."

Well, I've just given you several good ideas. All you have responded with is "we are a small group of volunteer developers! I don't see how we can do that!" I hear that a lot around here. That and "The volunteer developers work on what they are interested in. If we do not like something, we change it. If you want something changed you will have to do it yourself by submitting a patch. That's just the way it is."

Don't you see that it is just that message that is preventing others from joining in? If one of the things you need is project management help, and the SME role, and other stuff that is not core development, but the only way onto the team is to submit patches, then you will not get the needed help. Ever. And you will be stuck plodding along as you have been, with far too few putting in far too much work, wondering why no one will help more.

Believe me, it is NOT because people do not understand the situation!

I have never heard anyone say "We need to get better organized. Would someone who is good at managing development efforts please volunteer to help us out? We'll tell you who we are. We'll tell you what we want to do on the project and what we would like to get out of it. Perhaps you could then tell us what else is needed to get to a 1.0 release in a reasonable time frame." Wouldn't it be lovely if that were to actually happen?

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120228/b3a94b75/attachment-0001.html>

2012/2/29 Everton Vieira

Ok, I understood the fundamental goal of the project management etc. improvement was to make it easier for potential new developers (like you) to jump in and pick tasks. Did I misunderstand it? Now, your answers indicate you don't really know what you want. How does fixing a bug or creating a new feature become easier if it is listed in a project management GUI? It doesn't, you still have to learn and edit the code.

I filled my own and Mattias' data in the developers page. It is the "organization chart" that was requested:
http://wiki.lazarus.freepascal.org/Developer_pages

Then there is the roadmap page. It already contains tasks and people responsible for them. It is not up to date but can be updated: http://wiki.lazarus.freepascal.org/Roadmap

Everton, could you please explain the problems you face in a more detailed way. Now this is all very abstract, like everything becomes easy with a project management system.
That is, if you still want to learn and contribute. If you don't, it's OK, too.

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/da23c0b8/attachment.html>

No, you did not misunderstand, this is very like the intend.

Now, your answers indicate you don't really know what you want.

Of course i dont really know what i want in this matter because doesn`t matter what i want. Is a project management, the concept of it is well know.

How does fixing a bug or creating a new feature become easier if it is listed in a project management GUI?

By start, the talked about it would be grouped. The info would be formatted.

It doesn't, you still have to learn and edit the code.

Certainly is suposed so. But is very different when theres some lines saying what that code is already doing. And some lines to saying what is missing, and what was already be talked about, by who, everything in a formatted way. And i think, in my humble way of view, that a GUI would facilitate and much more likely draw people to help.

I filled my own and Mattias' data in the developers page. It is the "organization chart" that was requested: http://wiki.lazarus.freepascal.org/Developer_pages

Do not see any i saying as a request.

This is not about me. Why make this about me? This is about the group. From where i came from we have this saying: one andorinha bird doesn`t make summer. How can i tell this better. This meant that one can not make much, is the group that can make much.

And of course i never said that: "everything becomes easy with a project management system".

Juha

But i admit, maybe i`m wrong. That`s ok too. The project management in a open source environment, maybe is bad idea. Who never make some mistake?

And of course is not in this struggling path that we can make a community that really cooperates.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/b448d754/attachment.html>

Hans-Peter Diettrich wrote

What's missing from the current documentation tools?

After doing an addition to the help sources (supposedly using FPDoc, I did not yet try to use it, but found the discussions on your recent improvements to it very encouraging), how to (quite automatically) create from the svn sources (with my additions) a combined Lazarus offline help (in order to test the additions) that includes all aspects like Help-on-Help, FPC-Language, IDE, RTL, LCL, user additions, ... ?

-Michael

Sorry, I will return to you guys later about the project management issues. I am busy for some time now.
I try to pick the essential parts. You could also think of the details of how to implement some things.

Regards,
Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/7589a9b0/attachment.html>

Juha Manninen wrote

This was the best idea so far. I think there is open source project management programs available. However there is a big difference between professionally run SW projects and hobby open source projects:

The term you look for is community driven project, not hobby. Many people working on larger open source project can do so in a professional environment.

It is just that the project direction is not owned by a company.

Note that many hybrids exist (like e.g. Canonical Ubuntu and Redhat's Fedora).

Now, your answers indicate you don't really know what you want. How does fixing a bug or creating a new feature become easier if it is listed in a project management GUI? It doesn't, you still have to learn and edit the code.

This is where documentation is helpful. The LCL is so complex nowadays, that a newbie cannot figure out everything himself.

My experience with unmanaged open source projects is a roadmap that contains all the tasks, which the experienced coders don't want to do themselves, or for which they have no like tasks
for newcomers :-(

DoDi

That's what I wrote the FPDocManager for. It allows to create local documentation, except for the language and other issues which are not based on code and for which the sources are unavailable.

I don't see a need for combining everything into one help file, be PDF or CHM.

DoDi

2012/2/29 Marco van de Voort

Marco, do you have more experience of the project management issues in community driven projects?

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/308e814d/attachment.html>

Hans-Peter Diettrich wrote

I don't see a need for combining everything into one help file, be PDF or CHM.

Not one file but e.g. one multiple-file viewer. It should be possible to search for information (keyword combinations) across the different "files".

-Michael

I'm not familiar with CHM, don't know how this could be achieved. But I assume that such a feature should be available already - who knows more?

DoDi

Hans-Peter Diettrich hat am 29. Februar 2012 um
18:17 geschrieben:

to

> search for information (keyword combinations) across the different

"files".

I'm not familiar with CHM, don't know how this could be achieved. But I assume that such a feature should be available already - who knows more?

Google can search in the wiki and the fpdoc pages on the server.

For the offline version a tool is needed. Several people are implementing search engines. I have no recommendation yet.

Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120229/817166e7/attachment-0001.html>

Delphi doesn't seem to have problems with a search across helpfiles. Every help system provides at least a keyword search, so that IMO it is only a question of providing the right (merged?) keyword lists.

DoDi

I've followed several for years. The BSD forks even 18 years.

Usually they are driven by a foundation and/or core team. Much like FPC nowadays, with occasional alliances with commercial parties that sponsor a certain development.

There are not many alternative routes.

2012/2/29 Marco van de Voort

I was hoping something more concrete and detailed, like ideas for helping new potential contributors to get a softer landing. That was the original idea of this thread.

Rich Saunders proposed "SMEs", people to intermediate between core developers and users. It may be a good idea, I only wonder how would it be organized in practical day-to-day life.

Many issues discussed here could be solved by improving documentation. Especially there should be a page listing tasks suitable for new people. However that does not change the management anyhow, it only helps people find those things easier.

So, what does the management mean in practice? Should Lazarus be managed differently from how it is managed now?

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120301/f4a22383/attachment.html>

So, what does the management mean in practice? Should Lazarus be managed differently from how it is managed now?

IMO it's not so much a matter of management, but of mind shift. The developers should share more of their knowledge, apart from only writing code. Until then every management attempt will be ineffective.

BTW this is not a criticism on Lazarus only, I found that attitude in many open source projects, and small (one-man) companies. Failure to educate co-workers is usually justified by a lack of time ("busy with more important things"), and results in never decreasing work load.

DoDi

While you have identified one issue that may not be helped by a change in project management, there are other issues that will be helped. So don't just focus on this one thing and say "every management attempt will be ineffective".

Well but it is a question of philosophy then, isn't it?

"provide what is required (answer questions)" versus "provide all (or some/lots) upfront"

It does still cost time to write up all the info, and guarantees nothing. While if someone wants to do work on something, there are much better chances that the work (providing infos/answers) will bear fruits. So the 2nd seems much more cost efficient. [read 4 paragraph below "flood of seekers", before answering to this]

To be noted. This is *not* about docs how to *use* the code, but about how to *extend* it.

Sure some say, providing upfront, will attract more new developers. I have doubts, but I do not know.
Getting individualized answers to your questions, rather that having to go through masses of docs, seems far more attractive to me.

Leaves to talk about the quality of those answers. But should indeed that quality lack, then what makes any one thing that the docs would be better in quality?
And should the person who could answer become unavailable, then yes indeed documentation would help (until outdated, as the sack of a maintainer would lead to this)

In comparison it seems to me, that for the seeker "answer" vs "doc" has similar efficiency, but for the provider docs only become of interest, if there is a real flood of seekers.

Just my opinion...
(It is only 4 years I was a seeker myself, so I do speak from experience)

--------------
Oh, and because it may get mentioned. Yes answers often encourage/require to read the code, in order to understand. But again, if docs are done by the same people, they would do the same.

I experience the same from time to time in MSEide+MSEgui project. People complain missing documentation and write if there were good documentation tools (which actually means if I would make them) they and other users would write documentation.
Don't believe such statements, it is not true. The mentioned Lufdoc from Lars is such a good tool for user contributed source documentation, it exists since a long time. AFAIK there is not a single Lufdoc contribution from MSEde+MSEgui users other than Lars. The only thing what would happen if you or me would build the perfect documentation tool is that they would use that tools in their projects... People who are willing to work on documentation are able to work with existing possibilities or improve the tools oneself.

Martin

Hans-Peter Diettrich wrote

I'm not familiar with CHM, don't know how this could be achieved. But I assume that such a feature should be available already - who knows more?

That is why I mainly concentrated on DocView and culpably ignored CHM help.

-Michael

Very easy. People do things. Not people try to force other people to do things, or try to extort other people to do things (if you do this, I might help out, or many other people will come).

Don't blame the tools, don't blame core, don't blame the weather, just start.

That is also what is wrong in these threads. All these threads about what is wrong with the docs have combined hundred times more lines then were contributed externally (by non core committers) to the docs.

Marco van de Voort wrote

Don't blame the tools, don't blame core, don't blame the weather, just start.

Sorry, I tried to keep my moth shut, but I can't.

If we want contributors who help enhancing the documentation, we are addressing quite normal users that should be able to do this using "!easy to use" tools, but who are not able to create those tools. (With no request to anybody to do any additional work) it is obvious that one step is necessary before the other one.

-Michael

The angle is of course in the 'easy to use'.
You can hide behind that excuse forever.

That's what Marco meant with "Don't blame the tools".

So yes, with your statement, you do blame the tools.

Well, please don't. Just document.
We'll fix any errors you make (if any), don't worry.

Michael.

I don't agree. I think it is perfectly possible to do it now. Yes it could be better, but I think it is perfectly possible now.

I wonder what's the intented purpose of your "management". In my understanding a management will give instructions, which then are *obeyed*. Everything else is "talk" about a project, which can happen in any place (mailing list, forums...).

DoDi

In either case the answer has very *practical* consequences.

"provide what is required (answer questions)" versus "provide all (or some/lots) upfront"

You assume that all questions *have* to be asked. But with insufficient upfront information it can require many questions (and answers), until the discussion reaches the *essential* points.

It does still cost time to write up all the info, and guarantees nothing. While if someone wants to do work on something, there are much better chances that the work (providing infos/answers) will bear fruits.

This finally explains the often confuse and inconsistent implementations, found across the entire LCL :-(

And should the person who could answer become unavailable, then yes indeed documentation would help (until outdated, as the sack of a maintainer would lead to this)

Just to prevent such an unwanted situation, the initial documentation should accompany the implementation, or follow it immediately. Consider the way how patches have to be acknowledged first, before they become part of the code base. The same principle could be applied to all *new* work on the code base, except bug fixes.

In my experience it's helpful *also* to the implementors, when they have to write a few lines about the purpose or intended used of their work. What cannot be explained in a few words is almost a bad or inconsistent implementation, that better should be changed before committing.

DoDi

I experience the same from time to time in MSEide+MSEgui project. People complain missing documentation and write if there were good documentation tools (which actually means if I would make them) they and other users would write documentation.

Tools are not a replacement for content :-(

Don't believe such statements, it is not true. The mentioned Lufdoc from Lars is such a good tool for user contributed source documentation, it exists since a long time. AFAIK there is not a single Lufdoc contribution from MSEde+MSEgui users other than Lars.

Searching the *web* returns only a few Lufdoc pages, with almost no content. This indidicates to me that the tool has never been used for any purpose, except demonstrating that it is there. MakeSkel can be used for that job as well.

The only thing what would happen if you or me would build the perfect documentation tool is that they would use that tools in their projects... People who are willing to work on documentation are able to work with existing possibilities or improve the tools oneself.

ACK

But as mentioned above, what result can be expected when writing documentation is considered the task of *unrelated* people, which have nothing but undocumented source code as a starting point?

You (and others) seem to believe that there exist people, which are both able to understand the undocumented code of others, *and* are able to document it in a reasonable way, *and* find it more fun to write documentation for others (and for free!), instead of writing their own code. A very realistic assumption, indeed :-(

DoDi

Please tell us *which* documentation tools you tried already, and *why* you found them unusable.

DoDi

2012/2/29, Juha Manninen :

I was hoping something more concrete and detailed, like ideas for helping new potential contributors to get a softer landing. That was the original idea of this thread.

Well, it's not so concrete, but this book might help clarify some topics on the Lazarus management:

Producing Open Source Software - How to Run a Successful Free Software Project

http://producingoss.com/en/index.html

No, that is not the "management" I am talking about. I'm talking about more a coordinator role, an organizer. Here a manager is someone who knows what's going on and who is doing what. Hopefully they will also know the history and reasons why things are the way they are.

For example, a documentation manager would know how the documentation is organized, who has contributed what parts, who is currently working on what parts, and why it is done the way it is done. That person would be the best one to respond to any questions on the mailing lists about problems with the documentation. That person does NOT have to be a current developer, in fact probably should not be. But they should know the correct person to ask a specific question of. So they can translate a problem/issue/question from a user and say it in a way that is least likely to bother the expert being questioned.

The project could have
- a "build manager" who coordinates all the builds for various platforms, ensuring that each gets attended to when necessary
- a "communications manager" who keeps the mailing lists running smoothly and perhaps also acts as moderator
- a "public relations manager" who organizes the public presence of the project, ensuring that the project looks alive, organized, and attractive to newcomers
- a "quality manager" who organizes test suites, recruits testers, ensures testing is considered when new features are proposed/added

These are all tasks that the core developer team can be freed from doing.

Of course. Both ways have pro and con, both have advantages and disadvantages. And I thought, that I had made that clear, in what I wrote.

Each developer, contributor or other person, has a certain amount of time. This time gets invested. As with any investment one has to make a decision. based on philosophy and knowledge and other factors. (The same knowledge still leads to different results, depending on the philosophy followed.

Well if certain questions are ask often enough, so they create more work to be answered, than documented, then they probably will be documented....

Yes I see, for the new-comer, this is less attractive. But it should be possible to see that for those who answer-or-document this is easier. (As they can choose the cheaper way).
The previous given answers are not lost. They can be copy and pasted into the future doc.
They can also be found in the mailing list archives.

So again it is philosophy. Is the potential newcommer, who will read a small selection of the (assumed complete) docs, worth the work of writing this doc (including the parts that will never be read (even if only because the got replaced due to updates/changes/refactor..., before any one needed them)?

I acknowledge the "nice to have", but I do not think "at all cost".

I consider this a sarcasm gone badly wrong.

If those kind of implementation exist (rather than just being perceived as such by individuals), then for those there are many reasons possible. Many of which would still apply, even if ass the docs existed. What makes you thing out of all those reasons, it must be the missing docs?

Yep you are describing a philosophy here. One of many possible.

Documentation readers will easily find what's wrong with an uncoordinated design, and can point the developers there. Then each involved developer can study the documentation of the others, instead of figuring out what the might had in mind when implementing their isolated parts.

E.g. I'm voting for a layout manager interface since years, derived from the already existing DockManager interface. But in the meantime many features have been implemented that make it almost impossible to add layout managers to the TWinControls. Even docking has been broken, and the IDE layout management follows another and again different and incompatible way. The time, spent in such different approaches, could have been used much better.

DoDi

Martin Schreiber wrote

Don't believe such statements, it is not true.

My experience of > 15 years of OSS development as well. Valueable ontributors find their way to fix things, write docs etc. The people complaining about bad tools, bad docs, bad whatever, will never be valueable contributors. If one explains one thing or fix another for them, those will fail with the next step then. In the beginning I wasted a lot of time explaining people things "if you explain/fix me this, I can start" etc. but time have shown, this makes no sense. So I just do my work, capable and motivated people will find their way.

IIRC the layout was discussed long ago per mail, you did ask questions and iirc, they where answered.

If hypothetically:
- documentation was created which stated the concept of current layout implementation
- and also stated that this will (if not for any other reason then at least for compatibility) will be kept as it is

would you then be happier? Would then it be ok for you, and would then your desire for a layout manager be gone?

I do not thing me add: I would myself like nore modular concepts for layout. But I do not know if it can be done at reasonable cost (speed, memory, and compatibility). If I had time I would investigate. (I have not the time)

More than documentation, I would need test cases (If I would work on it, I would create them). Documentation I can misunderstand, and then my changes will break things. Testcases are better on catching those issues (and by doing so, they will help me understand)

There are wiki pages, documenting how layout works (IIRC there where some recent mail involving you and that doc)

Yes they do not tell you about the internal organisation about the data involved. But what can I say: it is my firm believe, that given the current situation (project size, number of people involved, number of people seeking to be involved) this is better done by asking question. This may change in future.
But there it is my believe that such change (e.g actually documenting those things up front) is to be a *reaction* to changes of the situation (size/people).

I accept you believe otherwise. I accept and applaud that you seek to convince others.

--------------
About how to define good and bad implementation or concepts.

I guess it is rather the concept/design you complain about? After all, if the design was good, but badly implemented it would likely be easy to fix?

When 4 years ago, I first looked at the debugger, I thought the design was rather bad. Now that I learned more about it, I can only applaud Marc for the incredible foresight he put into it (sure some things where changed, but many of the general concepts still stand).

Would it have been easier, if it had been documented? Not at all, or very little. Marc had back then answered all my question. So the issue wasn't getting or having the info. It was for me to familiarize myself with the huge amount of code. That simple takes time.

That`s true. To get the "softer landing" improving the doc (and i think the ways of it) would be enough. The project management is more about to lead the people to achieve common goals. I don`t know how you people from the core lives with so few contributors. The high goal of this thread is to improve that.

About management from the wikipedia: "Project management is the discipline of planning, organizing, securing, and managing resources to achieve specific goals."

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120301/3f495e1f/attachment.html>

2012/3/1 Everton Vieira

Right... if you honestly wanted to improve the situation you could start contributing yourself.
Until now we have seen only this abstract nonsense from you.

Yes, I can read wikipedia. My question included the "in practice" part.

DoDi and others!!!
Please don't hijack this thread for whining about documentation and docking and whatnot! You can do that in another thread if you must. Besides, you are supposed to improve the documents, not whine all the time like a baby. I don't know what is wrong with you.

I plan, hopefully during Friday, to collect some valid points about how this project should be visible to outsiders, in a constructive way. It really doesn't help things when this thread is filled with irrelevant whining, pushing the signal/noise ratio close to zero. Is it a collective whining period now or what?

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120302/d5f0e587/attachment.html>

Ok. I shall make no more comments on that.

The "in practice" is the system itself. It will depend on the politics adopted. This is not abstract. I`m not in the position to say on that. Marco?

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120301/0365d330/attachment.html>

Be warned, below there will follow a lot of personal opinions. ;)

Maybe it's a bit more than only improving documentation itself. The project management part of it is to care for keeping docs up to date and keep the shape following the needs. An example would be some kind of general info pages about how the project is driven. Special index pages or future plans come to my mind here.

Another issue with that is already in the works, that is transferring content from the wiki to other doc parts. But this too is not only a technical problem but it has to be done regularly (whenever necessary or before releases or by time interval) and watched a bit. Someone has to decide which parts are ready to get moved.

So, what does the management mean in practice? Should Lazarus be managed differently from how it is managed now?

No,the management is mostly fine as is. It it's only sort of "hidden" or not easy to step in for newcomers. I think the missing beginners page could do a lot, it can tell people shortly how things work and that problem are best handled on the mailing lists (although it is sometimes challenging to folow all that traffic ;). This beginners guide should be visible not only on the wikis starting page but on the home page of the project, at least as a link to the wiki.

Standard project management procedures only apply partly here. There is no ressource planning, no strict time schedules, no accounting, to name a few. And the project is not as big as ohter open source project requiring formal procedure for anything to be done. As long as the mailing lists can handle the amount of questions they are perfect for handling most things. And the persons answering question do an excellent job in answering, fixing problem in code or with web servers, very quickly as we all now.

Since those problems pop up from time to time it may be a good source of information to scan the mailing lists archive for the type of requests from newbies to get the most wanted issues.

Please note that I already contributed to the project, both code and documentation. In this thread the *observations*, made during that work, certainly are on-topic.

When I find something that went wrong in the past, we should check how such flaws could be reduced or prevented by certain means, e.g. by a better management.

Your comment seems to prove my impression, that the management discussion is limited to "do whatever you like, but don't change the current procedures". If so, then I apologize for my boring contributions.

DoDi

2012/3/2 Marc Santhoff

There is already such page :
http://wiki.lazarus.freepascal.org/Lazarus_Development_Process but it is difficult to find. I plan to update it and get a link somehow to main page (if I had rights).
Now only there is something badly wrong with the wiki server. It is very slow, browser timed out when I tried to update something.

There is already a link for developers page in Development_Process page. I was thinking to explain the tools used and project organization, too. ================================

Tools:
-------
There are 6 web-based -tools to help manage the development and to communicate.
* Lazarus main web page (www.lazarus.freepascal.org).
* Forum (http://lazarus.freepascal.org/index.php?action=forum).
* Mailing list ().
* Chat line (#lazarus-ide).
* Wiki pages (http://wiki.lazarus.freepascal.org). They document Lazarus usage and internals. Can be edited by anyone after logging in...
* Issue Tracker for reporting both bugs and feature requests. It supports also simple project management features. A bug can be assigned to a developer and its target release and priority can be set.

For documenting LCL library there is Documentation Manager (?) and FpDoc. The source document files are XML, many help file formats can be generated from them. Links...

For creating program code Lazarus itself is used (naturally).

Organization:
----------------

___ Developing program code and applying patches ___: The recommended way to contribute code for Lazarus sources is to first create a patch (link Creating_a_Patch) and then upload it to a new report in issue tracker.
The developers with commit rights verify the patch and apply it if valid. See Developers_Page for info about developers and their areas of expertise.

___ Web-tool administration, the responsible person ___: Server with Lazarus main page and Forum: ???
Mailing list server: ???
Chat server: ???
Wiki server: Vincent Snijders
Mantis Issue Tracker server: ???

In the other thread "Missing Documentation" Vincent mentioned he doesn't want to continue as wiki admin.
Samps Okholm and Richard Mace immediately offered their help. It would be stupid not to accept it, IMO.
I have no idea who are the admins for the other servers. Maybe the info is buried somewhere in wiki.
The web tools work well except for the wiki. The search is poor and now it is slow.

___ Public Relations ___:
The goal is to advertise Lazarus on different ways. Internet sites related to programming languages / tool and Linux distributions may be good candidates.
More frequent Lazarus releases will also work as a (semi-)automatic advertisement. Release announcements are typically notified on many sites. The responsible person : Position is open!

___ Release schedule ___: (the page already has info of releases up to 0.99) A new time-based release schedule will be used (! note, this is my proposal and not approved by other devels but there are signs it could be approved !).
Until now the release cycle has been long. It requires a set of bugs to be fixed and then verifying the quality with a test period. Now Lazarus is mature enough for a time-based schedule.
Most other mature projects have it, too.
This has at least 2 benefits.
1. Users would not need to use the development version only because the released version is so old.
2. A release announcement works as a free advertisement. (See Public Relations).

___ Release Management ___:
Release Manager person: Vincent Snijders
Build tester for Windows: Position is open!
Build tester for Mac: Position is open!
Build tester for Linux Debian: ???
Build tester for Linux RPM: Position is open!
Build tester for BSD: Position is open!
Build tester for xxx: Position is open! (I don't remember all platforms supported)

Now the fact is that Vincent has less time and energy than before for this task.
It may be that Release Manager position is open, too. (Correct me Vincent if I am wrong)
Build testers are needed because (according to Vincent) the building itself is easy if you have a remote connection (ssh) to a server but you can't test a graphical program on that server.

___ Updating Fixes Branches ___:
Bug fixes are backported from trunk to the fixes branch by these people: 0.9.30.x: Vincent Snijders / Juha Manninen
0.99.x: Maybe Juha Manninen (=me)

================================

That was the Development_Process page.
The Developers_Page would list also other prominent contributors, not only core developers.
They can be called SMEs (subject matter experts) if needed. It would not really change their position but just make it more visible to new people.

The updated page would improve the first impression for new potential users / contributors and make things more visible, as was requested. It also adds tasks which didn't exist before (Public Relations) and clearly states some positions to be open.
So yes, it tries to fix the project's organization and management, too, not only documentation.

The development process itself works very well. This includes the people (SMEs or whatever) answering questions on mailing list and on Forum. You guys failed to see that because you have not participated in the development.
Many other things around it don't work as well. Partly it is because the project is getting mature.
Things like "First Impression" and "Public Relations" were not important with the early, buggy versions of Lazarus but now they are.

Other developers would need to :
- approve the ideas (unless they are wrong)
- approve some people for open positions
- figure out who has admin rights to the web-tool servers and pass the keys forward if needed.

I also hope this doesn't lead to another endless debate ...

Juha
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20120302/ae0541bd/attachment-0001.html>

If the situation hasn't changed then (according to fpc-core) someone is mirroring the wiki using a tool called HTTrack (I won't link it) which not only slows down the wiki, but also e.g. www.hu.freepascal.org.

If that person is reading this list: Please stop it!

Regards,
Sven

Hans-Peter Diettrich wrote

Please tell us *which* documentation tools you tried already, and *why* you found them unusable.

(Not really wanting to enlarge the discussion even more, but as I have been directly asked: )

Being sure that IDE help only makes sense to me when it is usable offline and can search across all "issues" (e.g. if doing F1 in some word, a decent text should be provided, may the word be a keyword of the language, of the RTL or of the LCL, many months ago I asked about this in the mailing list. While I only recently learned that the CHM help in fact is supposed to support this, as well, at that time, only Graeme answered that DocView is the tool I need, and thus I concentrated on that and tried to generate all the necessary *.inf files from the svn content. I failed in spite of Graeme's hard trying to guide me.

Thus gave up, as I thought I would be unable to review any change I would locally do in the svn based help source files. Only very recently I learned that FPDoc is supposed to be so tightly integrated in the Lazarus IDE, that local changes made FPDoc should immediately (without any "compiling") be activated and be reviewable using the IDE. OTOH not all parts ("issues") of the docs seems to be the target of FPDoc.

Right now, DoDi seems to do a great job enhancing FPDoc regarding To-Do annotation and make it more usable.

So I obviously did only some testing, evaluating and provided just suggestion (that might sometimes sound like complains).

This obviously qualifies me as a troll and so please ignore me.

Thanks,
-Michael