On Jan 4, 10:53 am, Ali Afshar <[EMAIL PROTECTED]> wrote: > I think this is an excellent idea, and really appreciate you helping out > like this
> It will help us write nice docs, and hopefully debate/merge new > interesting ideas. Excellent. Let's get started then. I'll make my suggestions if a direct way, but please understand that they are only suggestions. 1. We want to increase the signal/noise ratio wherever possible. That is, each page should discuss only one topic, so that those interested in that topic are not distracted by other information. 2. The main page, http://pida.co.uk/ should **above all** explain why a newbie should be interested in pida. You want to concentrate on what makes pida unique and interesting. Avoid **everything** else. I suggest 1-3 paragraphs telling how pida is different from all other ide's, combined with a prominent link to a page that will tell newbies everything they need to know about pida (so they will be interested in pida) **and nothing else**. In other words, the main page should only have the following: - A summary description for newbies and - Links to all other pages. Keep the main page totally simple, so that the what makes pida unique stands out. 3. Now we come to the most important part. This is the description (summary) on the main page of what makes pida unique, and the more lengthy description on the page called What makes pida unique? The present main page starts well. It says, "PIDA is different from other IDEs in that it will use the tools you already have available rather than attempting to reinvent each one." I would suggest moving the following from the handbook page to the main page: "There are many IDE around, and some are very good. But lots of them are also closed in the sense that they are limited in terms of extensibility or communication with other tools. On the other hand, some of you may want to change your editor for anything else, even if you have to rely on external tools to complete its features. PIDA was designed with these problems in mind. PIDA's motto is to reuse the tools that proved to be useful and solid, and to provide the glue for them. PIDA has a number of unique features, such as * Embedding Vim, Emacs or any editor. * [other main features here] * Using any version control system. " This really got my attention. Make sure newbies see this by removing everything else from the front page. The main page is most important for newbies. The second (getting started or overview) page is the second most important page. Assume that the reader will give you 5-10 minutes to convince the reader that pida is exciting. How will you do that? Probably by explaining how pida can actually let different tools to work together. Again, you have a good start: "PIDA is essentially a bunch of services bound together by a Boss. The services are discovered from service directories and loaded by a Service Manager for the Boss." Ok, this is a good start, but what does it mean? And how does pida use these concepts to make it possible to embed Emacs into pida? I'm totally lost by the following documentation. I need to understand the what a service is, and what a boss is, before you go into details. Is this clear? Ok. Enough for now. Let's assume I am reading the sentence: "PIDA is essentially a bunch of services bound together by a Boss. The services are discovered from service directories and loaded by a Service Manager for the Boss." What can you say in words (not code) that will guide my understanding? Here is where I am stuck. Edward P.S. Do you see how you have hidden the important stuff by burying it in mundane details? Details about menus, installation, etc. Put the docs about installation and menus and all the other details in separate pages so those details don't distract newbies. P.P.S. Here are some quotes from the pyxides discussion: "Yes, we actually send elisp across the wire for Emacs to execute. In addition to commands, we found it necessary to be able to respond asynchronously to Emacs events (e.g. when a new buffer has been opened). There is a small amount of information here about the hows and whys: http://pida.co.uk/trac/wiki/EmacsSupport And you can browse the emacs integration code (which I would guess is fairly PIDA-independent) at http://pida.co.uk/trac/browser/trunk/pida/utils/emacs/emacscom.py"; This also got my attention because it indicated that you could control Emacs from pida. What was important was *what* you can do with pida, not *how* you actually did it. A newbie doesn't want to read code to understand a product. You should clearly explain what the code does. In other words, the introduction should do all the "heavy lifting" for the newbie. EKR --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "PIDA" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/pida?hl=en-GB -~----------~----~----~----~------~----~------~--~---
