JDownloader Community - Appwork GmbH
 

Notices

Reply
 
Thread Tools Display Modes
  #1  
Old 23.06.2010, 15:20
remi
Guest
 
Posts: n/a
Cool Documentation strategies

EDIT : the thread where this discussion started can be found here :- http://board.jdownloader.org/showthr...t=17836&page=2

Quote:
Originally Posted by Gweilo View Post
I meant by online help in the application, or the wiki.
Both are full of stubs and outdated information.
It's outdated because jD changes all the time, because of HMI improvements or because the developers want to adapt it to the ever changing download world.

Quote:
Originally Posted by Gweilo View Post
Right-Click on most things in JD and it tells you nothing (maybe echoes the name of the button you selected) or takes you to an empty page in the wiki:
e.g. Settings/Link filter: that links to http://wiki.jdownloader.org/quickhelp/Link-filter -- which is empty.
Customer information about a feature should be written (and reviewed/approved) before it's programmed.

Quote:
Originally Posted by Gweilo View Post
Anyway, old posts referring to old versions and bugs aren't helpful when you want to know something about the current version. Any search will be full of irrelevant, and/or wrong, comments, and that will only get worse as the total number of posts grow.
Not necessarily, if you apply semantic web techniques. All posts are tagged with a date. If you link that with your program's features and their versions, you know what's relevant and what could be outdated.

Quote:
Originally Posted by Gweilo View Post
A forum is good for discussion, very poor as a reference.
True, but new search technologies can mine the immense amount of information/knowledge hidden in those forums.

Last edited by remi; 28.06.2010 at 13:55. Reason: indicated starting thread
Reply With Quote
  #2  
Old 23.06.2010, 19:33
Gweilo's Avatar
Gweilo Gweilo is offline
JD Legend
 
Join Date: Mar 2009
Posts: 725
Default

Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
I meant by online help in the application, or the wiki.
Both are full of stubs and outdated information.
It's outdated because jD changes all the time, because of HMI improvements or because the developers want to adapt it to the ever changing download world.
No, it's outdated because no one bothers to update it, even though it would take less than 1% of the time it takes to code these improvements.

And the WHOLE POINT of a wiki is that it's EASY to update, by users, not just developers.
You notice something is wrong or incomplete, you click "Edit" and fix it, and it's done.


Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
Right-Click on most things in JD and it tells you nothing (maybe echoes the name of the button you selected) or takes you to an empty page in the wiki:
e.g. Settings/Link filter: that links to http://wiki.jdownloader.org/quickhelp/Link-filter -- which is empty.
Customer information about a feature should be written (and reviewed/approved) before it's programmed.
That's how it works in a professional environment, when you have a paid editorial staff. But that's not how a wiki works.
And in any case, that's not happening here, and never will.


Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
Anyway, old posts referring to old versions and bugs aren't helpful when you want to know something about the current version. Any search will be full of irrelevant, and/or wrong, comments, and that will only get worse as the total number of posts grow.
Not necessarily, if you apply semantic web techniques. All posts are tagged with a date. If you link that with your program's features and their versions, you know what's relevant and what could be outdated.
And who is going to do all that linking?
Which would be much more tedious than just putting the latest and correct information in the wiki.

If you don't know the program, how can you decide what is correct and what is irrelevant?
If you do, why not just put it in the wiki so the next person can find it instead of having to sift through thousands of old posts?


Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
A forum is good for discussion, very poor as a reference.
True, but new search technologies can mine the immense amount of information/knowledge hidden in those forums.
If you spend the time to look for it, and can get past all the irrelevant and repetitious, and incorrect crap.


Have you ever used Wikipedia, or any wiki?
You seem to discount the whole concept in favour of some kind of AI data mining.
Perhaps you have an example of such a system in action that I can see what you're talking about?
Reply With Quote
  #3  
Old 24.06.2010, 12:34
remi
Guest
 
Posts: n/a
Cool

Quote:
Originally Posted by Gweilo View Post
No, it's outdated because no one bothers to update it, even though it would take less than 1% of the time it takes to code these improvements.
If there would be a process that forces developers to write the documentation before the programming is started, this wouldn't happen.

Quote:
Originally Posted by Gweilo View Post
That's how it works in a professional environment, when you have a paid editorial staff. But that's not how a wiki works.
And in any case, that's not happening here, and never will.
Are you implying that people who work as volunteers can't be professional and that all paid people work as professionals?

Quote:
Originally Posted by Gweilo View Post
And who is going to do all that linking?
Which would be much more tedious than just putting the latest and correct information in the wiki.

If you don't know the program, how can you decide what is correct and what is irrelevant?
If you do, why not just put it in the wiki so the next person can find it instead of having to sift through thousands of old posts?

If you spend the time to look for it, and can get past all the irrelevant and repetitious, and incorrect crap.
All this can be automated with a good query engine. The change logs and the SVN contain the data about the changes and the posts in the forum contain the creation/last edit dates.

Quote:
Originally Posted by Gweilo View Post
Have you ever used Wikipedia, or any wiki?
You seem to discount the whole concept in favour of some kind of AI data mining.
Perhaps you have an example of such a system in action that I can see what you're talking about?
Yes, I occasionaly edit wikipedia pages and I regularly use TiddlyWikis to distribute content.

One of the most promising implementations I've found a few months ago is OntoWiki. There probably are many more such initiatives.

Thanks for all your interesting remarks and questions.

Note that I don't like the term AI, because the term "intelligence" has never been clearly defined.
Reply With Quote
  #4  
Old 24.06.2010, 13:14
drbits's Avatar
drbits drbits is offline
JD English Support (inactive)
 
Join Date: Sep 2009
Location: Physically in Los Angeles, CA, USA
Posts: 4,434
Default

@ Remi,
Since you dropped the project, it is not relevant here and now.

@ Gweilo,
Remi is quite familiar with WikiText. What he was discussing was not realistic for this project, but is not data mining, but the opposite.

We are in serious need a Wiki editor. If you are interested, please contact support@jdownloader.org.
Reply With Quote
  #5  
Old 24.06.2010, 14:35
Gweilo's Avatar
Gweilo Gweilo is offline
JD Legend
 
Join Date: Mar 2009
Posts: 725
Default

Quote:
Originally Posted by remi View Post
If there would be a process that forces developers to write the documentation before the programming is started, this wouldn't happen.
Well, there obviously isn't such a process here. And it wouldn't be a great idea, since the implementation often changes from the original plan as it proceeds. Planned features are never implemented or don't work properly, or new ones added. Documentation should not describe what was planned, but what actually exists.


Quote:
Originally Posted by remi View Post
Are you implying that people who work as volunteers can't be professional and that all paid people work as professionals?
No, I'm implying that most programmers don't like documenting and unless forced to as a condition of employment, rarely do it.

And the people who might "volunteer" to do documentation aren't allowed to.


Quote:
Originally Posted by remi View Post
All this can be automated with a good query engine. The change logs and the SVN contain the data about the changes and the posts in the forum contain the creation/last edit dates.
No, I really don't think this would work, even if the software to do it existed. The SVNs are too cryptic to be helpful to users, and don't explain how to use new features at all. The forum is full of questions and sometimes partial answers, and much outdated information.
Reply With Quote
  #6  
Old 24.06.2010, 15:15
Gweilo's Avatar
Gweilo Gweilo is offline
JD Legend
 
Join Date: Mar 2009
Posts: 725
Default

Quote:
Originally Posted by drbits View Post
We are in serious need a Wiki editor. If you are interested, please contact support@jdownloader.org.
Okay. But the idea is that you let just about anyone edit. (Maybe anyone who has been a member of this forum for 2 weeks and made 2 posts, as a minimum qualification.) You need admins to control spammers and lunatics, but Wikipedia has shown that you get a better result by opening up than locking it down.
Reply With Quote
  #7  
Old 25.06.2010, 13:13
remi
Guest
 
Posts: n/a
Cool

Quote:
Originally Posted by Gweilo View Post
Well, there obviously isn't such a process here. And it wouldn't be a great idea, since the implementation often changes from the original plan as it proceeds. Planned features are never implemented or don't work properly, or new ones added. Documentation should not describe what was planned, but what actually exists.
That's something I sometimes hear, see and read about and it means that the business' processes can be improved a lot and costs (delays) can be reduced considerably.

Some projects and product development teams are suffering from scope creep and poorly defined or unclear requirements. A quality process can completely eradicate all these problems. There exist several governance frameworks with documented levels of process and organisation maturity that can be measured and as a consequence, managed.

Quote:
Originally Posted by Gweilo View Post
No, I'm implying that most programmers don't like documenting and unless forced to as a condition of employment, rarely do it.
That's an outdated conception of the software development process. Software should be manufactured like any other product. Like building a house or a car for instance. That's why there is specialisation of labour. Why isn't this simple and very old principle applied to all software developments?
Programmers like programming, let them program. Authors like writing documentation. Let them write documentation. Architects like to design models, etc. By specialisation and clear separation of responsibilities you'll increase the professionalism of the software development team. Just apply the 50 years old Object Oriented method to a software development team.

Quote:
Originally Posted by Gweilo View Post
And the people who might "volunteer" to do documentation aren't allowed to.
That's because their is no trust. The team are afraid that they'll lose control.

Quote:
Originally Posted by Gweilo View Post
No, I really don't think this would work, even if the software to do it existed. The SVNs are too cryptic to be helpful to users, and don't explain how to use new features at all. The forum is full of questions and sometimes partial answers, and much outdated information.
Processes do not necessarily have to be fully supported by software or be fully automated. The SVN and the board are databases. Nothing is more structured than a database. The timestamps in those databases could be used to scope the relevancy of the threads and posts in the board's database. Semantic web technologies avoid a lot of tedious work. A lot of it can be automated by using the meaning of links and other data items.
Reply With Quote
  #8  
Old 25.06.2010, 15:32
Gweilo's Avatar
Gweilo Gweilo is offline
JD Legend
 
Join Date: Mar 2009
Posts: 725
Default

Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
Well, there obviously isn't such a process here. And it wouldn't be a great idea, since the implementation often changes from the original plan as it proceeds. Planned features are never implemented or don't work properly, or new ones added. Documentation should not describe what was planned, but what actually exists.
That's something I sometimes hear, see and read about and it means that the business' processes can be improved a lot and costs (delays) can be reduced considerably.

Some projects and product development teams are suffering from scope creep and poorly defined or unclear requirements. A quality process can completely eradicate all these problems. There exist several governance frameworks with documented levels of process and organisation maturity that can be measured and as a consequence, managed.
Fine. But in a volunteer project, you can't force people to follow this process.
In any case, no point telling me, you have to tell the devs if you want to institute this.


Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
No, I'm implying that most programmers don't like documenting and unless forced to as a condition of employment, rarely do it.
That's an outdated conception of the software development process. Software should be manufactured like any other product. Like building a house or a car for instance. That's why there is specialisation of labour. Why isn't this simple and very old principle applied to all software developments?
Programmers like programming, let them program. Authors like writing documentation. Let them write documentation. Architects like to design models, etc. By specialisation and clear separation of responsibilities you'll increase the professionalism of the software development team. Just apply the 50 years old Object Oriented method to a software development team.
Very idealistic. Again, you have to get the devs to agree to do this. And they seem totally uninterested.


Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
And the people who might "volunteer" to do documentation aren't allowed to.
That's because their is no trust. The team are afraid that they'll lose control.
Wikis have administrators, they can rollback any edits or series of edits.

It seems that someone created the original documentation framework, including the wiki, and did an excellent job of it. But since then, for the last couple of years anyway, it has been neglected.

I never bother to look there myself any more, 90% of links to the wiki are stub pages with no information.

Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
No, I really don't think this would work, even if the software to do it existed. The SVNs are too cryptic to be helpful to users, and don't explain how to use new features at all. The forum is full of questions and sometimes partial answers, and much outdated information.
Processes do not necessarily have to be fully supported by software or be fully automated. The SVN and the board are databases. Nothing is more structured than a database. The timestamps in those databases could be used to scope the relevancy of the threads and posts in the board's database. Semantic web technologies avoid a lot of tedious work. A lot of it can be automated by using the meaning of links and other data items.
I really think that would be a big waste of time.

99% of posts here will be of no value to anyone a week later. It's mostly ephemeral bug reports, and random comments pro and con various things.

The only forum that might be an exception is the reconnect forum; and that really should be translated into 1) the script database in the program and 2) the wiki.

It seems the scripts included in the program have not been updated for a very long time.
Reply With Quote
  #9  
Old 26.06.2010, 13:32
remi
Guest
 
Posts: n/a
Cool

Quote:
Originally Posted by Gweilo View Post
Fine. But in a volunteer project, you can't force people to follow this process.
In any case, no point telling me, you have to tell the devs if you want to institute this.
I don't see why the status of volunteer would make any difference here. I give you one example of a process that volunteers have to follow : the registration process. What matters is management taking the right decisions. This is a public thread and all members, including management, can read it.

Quote:
Originally Posted by Gweilo View Post
Very idealistic. Again, you have to get the devs to agree to do this. And they seem totally uninterested.
I'm not sure of this. They can read the thread and do some research about best practices in project management and product development. Don't forget the jD managers are young and will need to learn by experience. In general, I don't underestimate people. I wouldn't underestimate jD's management, because jD still has no multi-platform competition.

Quote:
Originally Posted by Gweilo View Post
It seems that someone created the original documentation framework, including the wiki, and did an excellent job of it. But since then, for the last couple of years anyway, it has been neglected.

I never bother to look there myself any more, 90% of links to the wiki are stub pages with no information.
That's exactly for the reasons I gave before. You can't maintain documentation if documentation is not included in the software development process.

Quote:
Originally Posted by Gweilo View Post
I really think that would be a big waste of time.

99% of posts here will be of no value to anyone a week later. It's mostly ephemeral bug reports, and random comments pro and con various things.
I believe 80% of the replies I write are based on answers and issues I find in jD's board. I admit that I'm using better (more or less semantic) search techniques.
Reply With Quote
  #10  
Old 26.06.2010, 19:27
Gweilo's Avatar
Gweilo Gweilo is offline
JD Legend
 
Join Date: Mar 2009
Posts: 725
Default

Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
Fine. But in a volunteer project, you can't force people to follow this process.
In any case, no point telling me, you have to tell the devs if you want to institute this.
I don't see why the status of volunteer would make any difference here. I give you one example of a process that volunteers have to follow : the registration process. What matters is management taking the right decisions. This is a public thread and all members, including management, can read it.
Because in a paid job the management and/or clients can insist. In a volunteer job for freeware people choose how to spend their time. The things they don't like doing will be deferred, possibly indefinitely. How many projects do you see where documentation is full of "To do" statements; years later?


Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
Very idealistic. Again, you have to get the devs to agree to do this. And they seem totally uninterested.
I'm not sure of this. They can read the thread and do some research about best practices in project management and product development. Don't forget the jD managers are young and will need to learn by experience. In general, I don't underestimate people. I wouldn't underestimate jD's management, because jD still has no multi-platform competition.
It's not lack of talent or ability, it's lack of motivation. It's always "later", "after the next upgrade", or in other words, "never". Developers, especially young ones, like coding. So that's what they spend their time on. Everything else has a low, or zero, priority.

Quote:
Originally Posted by remi View Post
That's exactly for the reasons I gave before. You can't maintain documentation if documentation is not included in the software development process.
So you propose to enforce a new software development process?
Good luck with that.
Reply With Quote
  #11  
Old 27.06.2010, 14:57
remi
Guest
 
Posts: n/a
Cool

Quote:
Originally Posted by Gweilo View Post
Because in a paid job the management and/or clients can insist. In a volunteer job for freeware people choose how to spend their time. The things they don't like doing will be deferred, possibly indefinitely. How many projects do you see where documentation is full of "To do" statements; years later?
I think you underestimate the power and the advantages of open source software development. Currently, the best software is produced by open source software teams of volunteers. More and more companies understand this and have opened up their code.

Look at Wikipedia. Anyone can write and edit articles and still, the quality of these articles is high compared to the articles in expensive encyclopaedia written by paid experts.

As I said before, any process can be enforced. Management just needs to define the process. Developers who don't follow the rules, are excluded or can't contribute to the product. Professional people will understand it, amateurs not. This will increase professionalism and automatically attract better developers. A good professional doesn't want to be associated with a team of amateurs.

Quote:
Originally Posted by Gweilo View Post
It's not lack of talent or ability, it's lack of motivation. It's always "later", "after the next upgrade", or in other words, "never". Developers, especially young ones, like coding. So that's what they spend their time on. Everything else has a low, or zero, priority.
If management would clearly define a role or several roles for documentation writing, I'm convinced many people would apply. Why would so many people have volunteered for translating the .loc file? I'm sure many of these translators aren't programmers.
Why and how would I provide support if there wouldn't be an interesting support forum?
There are many people with a natural talent for authoring and I'm sure they can be found among jD's customers.

Quote:
Originally Posted by Gweilo View Post
So you propose to enforce a new software development process?
Good luck with that.
I never try to enforce anything, because I'm not one of jD's managers. I only try to give advice (and hope it's understood). A discussion like this helps a lot.
Reply With Quote
  #12  
Old 27.06.2010, 16:16
Gweilo's Avatar
Gweilo Gweilo is offline
JD Legend
 
Join Date: Mar 2009
Posts: 725
Default

Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
Because in a paid job the management and/or clients can insist. In a volunteer job for freeware people choose how to spend their time. The things they don't like doing will be deferred, possibly indefinitely. How many projects do you see where documentation is full of "To do" statements; years later?
I think you underestimate the power and the advantages of open source software development. Currently, the best software is produced by open source software teams of volunteers. More and more companies understand this and have opened up their code.

Look at Wikipedia. Anyone can write and edit articles and still, the quality of these articles is high compared to the articles in expensive encyclopaedia written by paid experts.

As I said before, any process can be enforced. Management just needs to define the process. Developers who don't follow the rules, are excluded or can't contribute to the product. Professional people will understand it, amateurs not. This will increase professionalism and automatically attract better developers. A good professional doesn't want to be associated with a team of amateurs.
You keep missing my point.
The people who are now allowed to write documentation, the "devs", are clearly not interested in doing it. And they refuse to let anyone else participate. Thus the current situation. Doesn't matter how many other open source projects are shining beacons in this regard, JD is not.
I know nothing about jD's management process, but again it's clear from the results that they place a very low priority on documentation, that no one is enforcing anything in this regard.

And I know all about Wikipedia, I've been editing articles there for years. Which is why it's so frustrating to see jD's wiki stagnating.

Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
It's not lack of talent or ability, it's lack of motivation. It's always "later", "after the next upgrade", or in other words, "never". Developers, especially young ones, like coding. So that's what they spend their time on. Everything else has a low, or zero, priority.
If management would clearly define a role or several roles for documentation writing, I'm convinced many people would apply. Why would so many people have volunteered for translating the .loc file? I'm sure many of these translators aren't programmers.
Why and how would I provide support if there wouldn't be an interesting support forum?
There are many people with a natural talent for authoring and I'm sure they can be found among jD's customers.
Sure there are plenty of people who could do it. They're not invited to.
And I still think that a forum is not and never can be used as primary documentation. It can stimulate discussion and provide material, but the basic difference is that a forum is dialogue. Documentation is not.

Quote:
Originally Posted by remi View Post
Quote:
Originally Posted by Gweilo
So you propose to enforce a new software development process?
Good luck with that.
I never try to enforce anything, because I'm not one of jD's managers. I only try to give advice (and hope it's understood). A discussion like this helps a lot.
Only if the people who have authority read it and care. Signs are they don't.
Reply With Quote
  #13  
Old 28.06.2010, 03:40
drbits's Avatar
drbits drbits is offline
JD English Support (inactive)
 
Join Date: Sep 2009
Location: Physically in Los Angeles, CA, USA
Posts: 4,434
Default

Open Wikis don't work in open communities without a huge amount of moderator work. Wikipedia has a special version of Wiki that contains a "discussion" ( sandbox ) page for each Wiki page. Only users who have made sufficient quality contributions in the discussion pages are given Wiki edit accounts.
Reply With Quote
  #14  
Old 28.06.2010, 05:22
Gweilo's Avatar
Gweilo Gweilo is offline
JD Legend
 
Join Date: Mar 2009
Posts: 725
Default

Quote:
Originally Posted by drbits View Post
Open Wikis don't work in open communities without a huge amount of moderator work. Wikipedia has a special version of Wiki that contains a "discussion" ( sandbox ) page for each Wiki page. Only users who have made sufficient quality contributions in the discussion pages are given Wiki edit accounts.
That's not true. Anyone who want to can edit Wikipedia, even anonymously, just using their IP as their "name".
Anyone who wants an editor's account can get one just by choosing a username and password.
You may be thinking of "Administrator" accounts.

One has to be complete jerk to have an account suspended, and then you can just get another one as easily.

It does not take a "huge amount of moderator work". The main problem is spammers. (Since you won't have explosive issues like Palestine to create edit wars.)

In any case, if you made membership of this forum with a (small) minimum number of posts as the qualification, that would pretty much eliminate spammers. (I wouldn't leave editing completely open to any anonymous user, that is asking for it.) Some wikis have a captcha before any edit is confirmed, even if you're signed in.

An administrator can roll back every edit a user has made in one operation if a spammer did get in and mess up lots of pages.

And discussion pages are a normal wiki feature; at least I see them in every wiki I've used (not just the original Wikipedia). Those aren't sandbox pages, sandboxes are in the user space, outside the normal name space and used for preparing articles and experimenting with formatting, etc.

Last edited by Gweilo; 28.06.2010 at 05:27.
Reply With Quote
Reply

Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump

All times are GMT +2. The time now is 21:18.
Provided By AppWork GmbH | Privacy | Imprint
Parts of the Design are used from Kirsch designed by Andrew & Austin
Powered by vBulletin® Version 3.8.10 Beta 1
Copyright ©2000 - 2024, Jelsoft Enterprises Ltd.