Would like to add 3 concise docs relevant to the majority of users
John Gabriele
I think the Guide (and the vast majority of novice Python users) would
benefit greatly from having three concise and opinionated docs right
at the top:
1. installing-module-distributions.txt
2. creating-module-distributions.txt
3. distributing-module-distributions.txt
The idea is that these would be short, clear, and would primarily
focus on the 90+% of users who just need the basic and most commonly-
needed information to quickly get done what they'd like to get done.
I haven't written these yet, but would like to at least get something
started.
Also, I'd like to add some text to the main index.txt page about the
focus of the Guide, and mention how -- for the majority of users --
those first 3 brief docs should give them what they need to know to
quickly get the job done. (Besides, it looks a little barren with just
that table of contents there. :) )
Thanks,
---John
Tarek Ziadé
> Hi,
>
> I think the Guide (and the vast majority of novice Python users) would
> benefit greatly from having three concise and opinionated docs right
> at the top:
>
> 1. installing-module-distributions.txt
> 2. creating-module-distributions.txt
> 3. distributing-module-distributions.txt
>
> The idea is that these would be short, clear, and would primarily
> focus on the 90+% of users who just need the basic and most commonly-
> needed information to quickly get done what they'd like to get done.
>
> I haven't written these yet, but would like to at least get something
> started.
I think we could reunite the doc in two parts:
1/ from the developer's point of view
2/ from the user's point of view
In that case, I would reunite your 2/ and 3/.
Last, take a look at what has been already written about pip in the guide,
so your chapter does references on it instead of repeating things. I think
you can manage to write those without too much overlap.
>
> Also, I'd like to add some text to the main index.txt page about the
> focus of the Guide, and mention how -- for the majority of users --
> those first 3 brief docs should give them what they need to know to
> quickly get the job done. (Besides, it looks a little barren with just
> that table of contents there. :) )
I would like that "index" page to be the overview page:
http://guide.python-distribute.org/overview.html I have started.
The diagram is the support for introcuding all parts of the guide. You
could probably
continue in the bottom of that page, and introduce all sections.
Next, maybe we could drop index.txt in favor of overview.txt and drop that ToC
The diagram is done with omingraffle and can be changed of course, I
have a licence
so I can do it if required.
Since you have interest in contributing in those areas, I will work on
the PyPI page on my side
Cheers
Tarek
>
> Thanks,
> ---John
>
--
Tarek Ziadé | http://ziade.org
John Gabriele
>
> I think we could reunite the doc in two parts:
>
> 1/ from the developer's point of view
> 2/ from the user's point of view
>
> In that case, I would reunite your 2/ and 3/.
Ok.
> Last, take a look at what has been already written about pip in the guide,
> so your chapter does references on it instead of repeating things. I think
> you can manage to write those without too much overlap.
Well, I think if we're going to provide users with a brief "here's how
you most often do it" doc, there's going to necessarily be a *little*
overlap (along with the references to the other docs too, of course).
That is, one doc (installing-distributions.txt) to quickly give most
users what they need most of the time, and another to give them the
full details when they need it (pip.txt, et al).
If a new Python user asks me, "Can you please just give me the
executive summary of the best way to install Python packages?", I'd
like to be able to say, "sure, it's simple" and point them to one
condensed doc that gives them what they most likely need right now
without them having to read through multiple (compatively) longer
docs.
If the installing-distributions.txt doc contains too many "for <this>
see [here]" links, I think that -- to new users -- it will look too
complicated and seem like there's a lot of yak shaving involved. I'd
instead rather have parenthetical "for more info on <this> see [here]"
links sprinkled throughout -- or better yet, included as footnotes.
---John
John Gabriele
> On Jan 2, 7:02 am, Tarek Ziadé <ziade.ta...@gmail.com> wrote:
>
> > I think we could reunite the doc in two parts:
>
> > 1/ from the developer's point of view
> > 2/ from the user's point of view
>
> > In that case, I would reunite your 2/ and 3/.
>
Ok. I just added the 2nd one (for users): "Basics: Installing
Distributions".
---John
Tarek Ziadé
I've added a glossary, so we can start to have common definitions for words like
"distribution". I've linked your section to that glossary and added a
virtualenv chapter
Tarek
--
Tarek Ziadé | http://ziade.org
John Gabriele
> I would like that "index" page to be the overview page:http://guide.python-distribute.org/overview.htmlI have started.
>
> The diagram is the support for introcuding all parts of the guide. You
> could probably
> continue in the bottom of that page, and introduce all sections.
Ok. Added content to overview page.
> Next, maybe we could drop index.txt in favor of overview.txt and drop that ToC
Hm. Well, having the "sitemap"-type table of contents is nice too.
I must say, it's taking all my restraint to not add
"DON'T PANIC" -- *Hitchhiker's Guide to the Galaxy*, Douglas Adams
to the top of that index.txt file. :)
---John
Tarek Ziadé
[..]
>
> Ok. Added content to overview page.
Nice. I suggest keeping the diagram at the top and refer to its parts
in your overview.
>
>> Next, maybe we could drop index.txt in favor of overview.txt and drop that ToC
>
> Hm. Well, having the "sitemap"-type table of contents is nice too.
>
> I must say, it's taking all my restraint to not add
>
> "DON'T PANIC" -- *Hitchhiker's Guide to the Galaxy*, Douglas Adams
>
> to the top of that index.txt file. :)
Ilan (who created http://s3.pixane.com/lenin_packaging.png) told me he
would work on a nice graphical design, for the Guide, so we should
have something quite nice :)