You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Tim Williams <wi...@gmail.com> on 2006/08/05 15:03:31 UTC
Site-author organization
I've tried to give this new organization the benefit of the doubt and
chalk my initial inability to find things up to it just being
something new. Now, having lived with it for a while, I still can't
seem to find things in here. Most of what I want turns out to be
under the "Developers" tab. The three main headings under there use
the most ambigious words I think:
"Getting Involved" - Isn't anything under the this tab really about
getting involved?
"Resources and Infrastructure" - Resources is way too ambigious to be
a part of a navigation scheme I think. Infrastructure also doesn't
carry much meaning when I think of an open source project. It turns
out that likely what most folks are looking for is really under here
(mailing lists, code access, and issue reporting).
"Best Practices and Procedures" - Again, I think it doesn't carry
enough common concrete meaning to be a part of a navigation scheme.
Do people know what they can expect to find when they click this?
"Project" - This is currently buried under "Getting Involveld". It
seems to me that there is some good information that should be given a
better spot.
If I'm the only one that feels confused by the current navigation
scheme I will get over it and eventually get used to it. If not,
maybe we could kick around some alternative schemes on the mail list
to improve it?
--tim
Re: Site-author organization
Posted by David Crossley <cr...@apache.org>.
Tim Williams wrote:
> Thorsten Scherler wrote:
> >Tim Williams escribi?:
> >>
> >> I've tried to give this new organization the benefit of the doubt and
> >> chalk my initial inability to find things up to it just being
> >> something new. Now, having lived with it for a while, I still can't
> >> seem to find things in here.
I agree that it needs attention. Not sure what.
As Ross said, Ferdinand just started to re-organise it
and obviously got called away to other things.
> >> Most of what I want turns out to be
> >> under the "Developers" tab.
For me this tab has two aims:
Direct developers to mail lists, issue tracker,
development tips, etc.
Try to make little distinction between being a
developer and being involved in the project.
> >> The three main headings under there use
> >> the most ambigious words I think:
> >>
> >> "Getting Involved" - Isn't anything under the this tab really about
> >> getting involved?
The menu needs a top-level "folder" label. It would be great
if we could tweak the code so that the top-level label
is optional. Same problem on the Welcome tab with About.
> >> "Resources and Infrastructure" - Resources is way too ambigious to be
> >> a part of a navigation scheme I think. Infrastructure also doesn't
> >> carry much meaning when I think of an open source project. It turns
> >> out that likely what most folks are looking for is really under here
> >> (mailing lists, code access, and issue reporting).
It is also duplicated at the top-level of this tab.
> >> "Best Practices and Procedures" - Again, I think it doesn't carry
> >> enough common concrete meaning to be a part of a navigation scheme.
> >> Do people know what they can expect to find when they click this?
> >
> >Nupp, it took me ages e.g. to find our docs to "Publishing Forrest
> >documentation"
> >
> >> "Project" - This is currently buried under "Getting Involveld". It
> >> seems to me that there is some good information that should be given a
> >> better spot.
Those three items could come up to the top-level.
> >> If I'm the only one that feels confused by the current navigation
> >> scheme I will get over it and eventually get used to it. If not,
> >> maybe we could kick around some alternative schemes on the mail list
> >> to improve it?
> >
> >I am as well confused. Do you have an alternative in mind?
>
> Not yet. I wanted to first see if I was solo in my being confused. I
> will think it through and post an alternative to the list for
> consideration. I'm of the opinion that folks looking at OSS and
> software in general have come to identify with certain keywords (code,
> download, mailing list, issues, etc.) and we should stick pretty close
> to those I think. I'll try to think through some top level navigation
> elements and we can go from there.
Please do. Good luck, i have tried on a number of occasions
and it is not easy. Ferdinand did a pretty good job. In one
of the previous threads we agreed that it needed more content
before the current scheme made sense. Anyway, i hope that we
can improve it.
-David
Re: Site-author organization
Posted by Tim Williams <wi...@gmail.com>.
On 8/5/06, Thorsten Scherler <th...@apache.org> wrote:
> El sáb, 05-08-2006 a las 09:03 -0400, Tim Williams escribió:
> > I've tried to give this new organization the benefit of the doubt and
> > chalk my initial inability to find things up to it just being
> > something new. Now, having lived with it for a while, I still can't
> > seem to find things in here. Most of what I want turns out to be
> > under the "Developers" tab. The three main headings under there use
> > the most ambigious words I think:
> >
> > "Getting Involved" - Isn't anything under the this tab really about
> > getting involved?
> >
> > "Resources and Infrastructure" - Resources is way too ambigious to be
> > a part of a navigation scheme I think. Infrastructure also doesn't
> > carry much meaning when I think of an open source project. It turns
> > out that likely what most folks are looking for is really under here
> > (mailing lists, code access, and issue reporting).
> >
> > "Best Practices and Procedures" - Again, I think it doesn't carry
> > enough common concrete meaning to be a part of a navigation scheme.
> > Do people know what they can expect to find when they click this?
>
> Nupp, it took me ages e.g. to find our docs to "Publishing Forrest
> documentation"
>
> >
> > "Project" - This is currently buried under "Getting Involveld". It
> > seems to me that there is some good information that should be given a
> > better spot.
> >
> > If I'm the only one that feels confused by the current navigation
> > scheme I will get over it and eventually get used to it. If not,
> > maybe we could kick around some alternative schemes on the mail list
> > to improve it?
>
> I am as well confused. Do you have an alternative in mind?
Not yet. I wanted to first see if I was solo in my being confused. I
will think it through and post an alternative to the list for
consideration. I'm of the opinion that folks looking at OSS and
software in general have come to identify with certain keywords (code,
download, mailing list, issues, etc.) and we should stick pretty close
to those I think. I'll try to think through some top level navigation
elements and we can go from there.
--tim
Re: Site-author organization
Posted by Thorsten Scherler <th...@apache.org>.
El sáb, 05-08-2006 a las 09:03 -0400, Tim Williams escribió:
> I've tried to give this new organization the benefit of the doubt and
> chalk my initial inability to find things up to it just being
> something new. Now, having lived with it for a while, I still can't
> seem to find things in here. Most of what I want turns out to be
> under the "Developers" tab. The three main headings under there use
> the most ambigious words I think:
>
> "Getting Involved" - Isn't anything under the this tab really about
> getting involved?
>
> "Resources and Infrastructure" - Resources is way too ambigious to be
> a part of a navigation scheme I think. Infrastructure also doesn't
> carry much meaning when I think of an open source project. It turns
> out that likely what most folks are looking for is really under here
> (mailing lists, code access, and issue reporting).
>
> "Best Practices and Procedures" - Again, I think it doesn't carry
> enough common concrete meaning to be a part of a navigation scheme.
> Do people know what they can expect to find when they click this?
Nupp, it took me ages e.g. to find our docs to "Publishing Forrest
documentation"
>
> "Project" - This is currently buried under "Getting Involveld". It
> seems to me that there is some good information that should be given a
> better spot.
>
> If I'm the only one that feels confused by the current navigation
> scheme I will get over it and eventually get used to it. If not,
> maybe we could kick around some alternative schemes on the mail list
> to improve it?
I am as well confused. Do you have an alternative in mind?
salu2
> --tim
--
thorsten
"Together we stand, divided we fall!"
Hey you (Pink Floyd)
Re: Site-author organization
Posted by Ross Gardler <rg...@apache.org>.
Tim Williams wrote:
> If I'm the only one that feels confused by the current navigation
> scheme I will get over it and eventually get used to it. If not,
> maybe we could kick around some alternative schemes on the mail list
> to improve it?
Your not the only one. I can't find anything either (see my previous
post on this topic). Ferdinand said he was had not completed what he
wanted to do, but that was quite some time ago now.
Unfortunately I have no time to fix it right now, so this mail is just
to support you (or anyone else) in whatever is done with the docs.
Ross
Re: Site-author organization
Posted by David Crossley <cr...@apache.org>.
Gav.... wrote:
> > From: David Crossley
> >
> > Here is one approach to clarify this section of the documentation.
> >
> > http://people.apache.org/~crossley/helper-tab.png
> >
> > I renamed the tab to be "Helper" ... that works both ways:
> > how to get help, how to help.
> >
> > I merged everything in the "Resources and Infrastructure" section
> > up to the top-level. There is a now a new Introduction page
> > (not yet finished) which will explain how to find and give help
> > rather than focussing on "contributing". The "Contrib" page
> > is now a link on the navigation menu.
> >
> > What do people think?
>
> Hmm, I'm not buying it at this stage, don't know why but am not liking the
> word 'helper' . Maybe it'll grow on me.
Try finding a better one. It took my wife and i
much of a driving trip to Sydney to arrive at that
one. We thought that it covered all possible uses
for this set of documents. Anyway if you can come
up with something else then please do.
> Apart from that, I still don't agree with the layout. I did make some
> suggestions earlier in this thread but they haven't been commented on.
Your second comment in that thread had already been answered
in the previous discussion. Your first comment i didn't know
how to answer. It seemed similar to previous suggestions.
> In light of your new design, I'll revise mine and comment on yours.
>
> I do like the idea of a new intro and moving the committer page.
>
> However, I think that we can still split up these topics further.
Why?
> Looking through the list of links there is very obviously areas of interest
> there that are for Developers only. So, I would not want to get rid of the
> developers tab.
I reckon that all links are for developers.
Sure there are users which will need to find the
mailing lists and perhaps the Issue Tracker. I thought
that the "Helper" name would attract users to this tab
and they would see that the first two items are what
they are looking for. While there, they might be enticed
to become developers.
> >From your 'Helper' tab then how about removing the following and putting
> them back into their own 'Developer' Tab.
I don't yet see how splitting it to two tabs
will assist.
> Contributing - Content needs splitting up, the top two paras relate to
> encouraging new users, the rest of it is surely 'dev only' material and
> could be moved to the developer tab in its own page.
I disagree. The whole thing is targetted at developers.
Users don't contribute. As soon as they do, they become
developers.
> ForrestFriday IRC - already stated as being a Dev only exercise (atm) so
> again could be moved to the 'developer' tab.
>
> Version Control - Sounds like dev only to me (where is that anyway?)
It would be a new page to explain everything about the
source control system. Where to get forrest via SVN,
how to do a checkout, which URLs, how to browse the ASF
SVN server for direct access:
http://svn.apache.org/repos/asf/forrest/
and how to browse it via ViewVC web interface:
http://svn.apache.org/viewvc/forrest/trunk
> Subversion - dev only
>
> Committer Notes - dev only.
>
> Browse SVN and Zone Testbed - where are these on your list, anyway dev tab.
"Zone testbed" is renamed to "Demonstrations".
For "Browse SVN" see the abovementioned "Version Control".
You say "dev only" for lots of the info. What other
group of people would want access to this stuff?
> All the rest remain on your 'Helper' tab - though will try to think of
> another name, if we can't then I'll get used to it.
>
> So summarising the above, I'm suggesting splitting the tab into two tabs,
> thinking of the future where we will put lots more examples and stuff in, it
> could be an idea to get an extra tab in there now.
The only bit that i see expanding is the "Best Practices".
I expect these to target developers and each doc have an
extra section for notes specific to committers for that topic.
Anyway, if you can come up with another design ...
-David
Re: Site-author organization
Posted by Ferdinand Soethe <fe...@apache.org>.
David Crossley wrote:
> Here is one approach to clarify this section of the documentation.
> http://people.apache.org/~crossley/helper-tab.png
Sorry to be late with my comments. Am travelling in the US and network
access is limited.
I'm not happy about 'helper'. Too hard to figure what it is supposed
to mean. And I'm really unhappy about merging the links to
infrastructure with those pointing to information and guides. My whole
idea in reorganizing this tab was to have an easy to find place for accessing all
the infrastructure that is separate from the guides and infos.
--
Ferdinand Soethe
RE: Site-author organization
Posted by "Gav...." <br...@brightontown.com.au>.
> -----Original Message-----
> From: David Crossley [mailto:crossley@apache.org]
> Sent: Friday, 18 August 2006 1:26 PM
> To: dev@forrest.apache.org
> Subject: Re: Site-author organization
>
> Here is one approach to clarify this section of the documentation.
>
> http://people.apache.org/~crossley/helper-tab.png
>
> I renamed the tab to be "Helper" ... that works both ways:
> how to get help, how to help.
>
> I merged everything in the "Resources and Infrastructure" section
> up to the top-level. There is a now a new Introduction page
> (not yet finished) which will explain how to find and give help
> rather than focussing on "contributing". The "Contrib" page
> is now a link on the navigation menu.
>
> What do people think?
Hmm, I'm not buying it at this stage, don't know why but am not liking the
word 'helper' . Maybe it'll grow on me.
Apart from that, I still don't agree with the layout. I did make some
suggestions earlier in this thread but they haven't been commented on.
In light of your new design, I'll revise mine and comment on yours.
I do like the idea of a new intro and moving the committer page.
However, I think that we can still split up these topics further.
Looking through the list of links there is very obviously areas of interest
there that are for Developers only. So, I would not want to get rid of the
developers tab.
>From your 'Helper' tab then how about removing the following and putting
them back into their own 'Developer' Tab.
Contributing - Content needs splitting up, the top two paras relate to
encouraging new users, the rest of it is surely 'dev only' material and
could be moved to the developer tab in its own page.
ForrestFriday IRC - already stated as being a Dev only exercise (atm) so
again could be moved to the 'developer' tab.
Version Control - Sounds like dev only to me (where is that anyway?)
Subversion - dev only
Committer Notes - dev only.
Browse SVN and Zone Testbed - where are these on your list, anyway dev tab.
All the rest remain on your 'Helper' tab - though will try to think of
another name, if we can't then I'll get used to it.
So summarising the above, I'm suggesting splitting the tab into two tabs,
thinking of the future where we will put lots more examples and stuff in, it
could be an idea to get an extra tab in there now.
That's it for now.
Gav...
>
> -David
>
>
>
> --
> No virus found in this incoming message.
> Checked by AVG Free Edition.
> Version: 7.1.405 / Virus Database: 268.11.2/422 - Release Date: 8/17/2006
Re: Site-author organization
Posted by David Crossley <cr...@apache.org>.
Here is one approach to clarify this section of the documentation.
http://people.apache.org/~crossley/helper-tab.png
I renamed the tab to be "Helper" ... that works both ways:
how to get help, how to help.
I merged everything in the "Resources and Infrastructure" section
up to the top-level. There is a now a new Introduction page
(not yet finished) which will explain how to find and give help
rather than focussing on "contributing". The "Contrib" page
is now a link on the navigation menu.
What do people think?
-David
Re: Site-author organization
Posted by David Crossley <cr...@apache.org>.
Ferdinand Soethe wrote:
> David Crossley wrote:
>
> > In the previous thread, Ross and i had strong opinions
> > about not making a distinction between "us and them".
> > We are all "developers". Some of us (mainly the committers)
> > make extra effort to do the tasks that keep the project
> > flowing. I have not yet heard any justification for making
> > a distinction. In fact i think that it would be dangerous
> > for the project health.
>
> I had and have no objection to your intention of not making a
> distinction between 'us and them'.
Ah, that was not clear to me sorry. The naming and
organisation suggestions seemed to make me think
that we were not on the same wavelength.
> And yet I still find the term
> developers misleading as many people would not consider themselves
> 'developers' if they contributed documentation. Just because we think
> of all of them as 'developers' will not change that.
Good one. This is a nice evolution to find one
of the key issues.
> 'Participation' seems like an excellent alternative, sorry I missed
> that post at the time.
Not sure yet. Need to put our wordsmith caps on.
> Apart from that:
>
> For users or developers looking for info to solve a problem I would
> take a different approach:
>
> Rather than creating a tab-name that will make people look for the
> mailings lists in the project tab, I would prefer to create additional
> references to these resources in the versioned docs.
That too. Perhaps an additional tab as well.
Going away today, will think some more after
the weekend.
> This way people can smoothly cross over from Forrest documentation to
> the extended documentation in the mailing list. A collection of
> pointers to important topics in the mailing list might help guide
> people this way or encourage writers to turn a topic into a piece of
> documentation.
Good ideas. I have often encouraged us to do that.
In the absence of full docs, just make a simple
link to some mail threads. Summarise content later.
A while ago i started a Jira category as another way
to grab mail threads.
> > The "Developers" tab includes a few documents under
> > the sub-section "Project". I reckon that these should
> > be moved up to the "Getting involved" section.
>
> Well yes. Although the project guidelines are slightly more than
> that (mission statement) and really talk about the project as a
> whole.
>
> In any case I'd suggest to place that at the top of the participation
> tab.
>
> In the longer term: I'd like to split this document into a
> mission statement that goes on the first tab and project by-laws that
> remain in the participation section. Wdyt?
Need to ponder that. Our inception resolution said
we need to maintain "guidelines", so i suppose no need
to be one doc.
-David
> >> - Resources and Infrastructure lists the tools and infrastructure
> >> available for people working for the project.
>
> > I think that it is way more that just that little group.
> > Developers want to participate in the mailing lists, and
> > want to search and add to the Issue Tracker, etc.
>
> OK, so why not add references to these resources to the tab that
> caters specifically to these people (Versioned Docs). Perhaps
> rename the tab 'Documentation' to make it more obvious.
>
> >> ...This could be a
> >> subheading to "Getting involved" but since it is needed quite often
> >> I left it at the top level to make it easier to find.
>
> > Perhaps we should merge these few resources into the
> > top-level section and rename it from "Getting involved"
> > to "Resources and Infrastructure" (or a better name).
>
> I'd really like to keep the clear distinction between the 'how can I
> participate' and the 'what tools can I use' parts of this tab.
>
>
>
>
> --
> Ferdinand Soethe
Re: Site-author organization
Posted by Ferdinand Soethe <fe...@apache.org>.
David Crossley wrote:
> In the previous thread, Ross and i had strong opinions
> about not making a distinction between "us and them".
> We are all "developers". Some of us (mainly the committers)
> make extra effort to do the tasks that keep the project
> flowing. I have not yet heard any justification for making
> a distinction. In fact i think that it would be dangerous
> for the project health.
I had and have no objection to your intention of not making a
distinction between 'us and them'. And yet I still find the term
developers misleading as many people would not consider themselves
'developers' if they contributed documentation. Just because we think
of all of them as 'developers' will not change that.
'Participation' seems like an excellent alternative, sorry I missed
that post at the time.
Apart from that:
For users or developers looking for info to solve a problem I would
take a different approach:
Rather than creating a tab-name that will make people look for the
mailings lists in the project tab, I would prefer to create additional
references to these resources in the versioned docs.
This way people can smoothly cross over from Forrest documentation to
the extended documentation in the mailing list. A collection of
pointers to important topics in the mailing list might help guide
people this way or encourage writers to turn a topic into a piece of
documentation.
> The "Developers" tab includes a few documents under
> the sub-section "Project". I reckon that these should
> be moved up to the "Getting involved" section.
Well yes. Although the project guidelines are slightly more than
that (mission statement) and really talk about the project as a
whole.
In any case I'd suggest to place that at the top of the participation
tab.
In the longer term: I'd like to split this document into a
mission statement that goes on the first tab and project by-laws that
remain in the participation section. Wdyt?
>> - Resources and Infrastructure lists the tools and infrastructure
>> available for people working for the project.
> I think that it is way more that just that little group.
> Developers want to participate in the mailing lists, and
> want to search and add to the Issue Tracker, etc.
OK, so why not add references to these resources to the tab that
caters specifically to these people (Versioned Docs). Perhaps
rename the tab 'Documentation' to make it more obvious.
>> ...This could be a
>> subheading to "Getting involved" but since it is needed quite often
>> I left it at the top level to make it easier to find.
> Perhaps we should merge these few resources into the
> top-level section and rename it from "Getting involved"
> to "Resources and Infrastructure" (or a better name).
I'd really like to keep the clear distinction between the 'how can I
participate' and the 'what tools can I use' parts of this tab.
--
Ferdinand Soethe
RE: Site-author organization
Posted by "Gav...." <br...@brightontown.com.au>.
> -----Original Message-----
> From: David Crossley [mailto:crossley@apache.org]
> Sent: Wednesday, 9 August 2006 10:04 AM
> To: dev@forrest.apache.org
> Subject: Re: Site-author organization
>
> Ferdinand Soethe wrote:
> >
> > Sorry for being so quiet for long time. Had and still have some
> > pressing personal issues to attend to. But I'm still reading and I'll
> > try to explain what I had in mind when I started this restructuring:
>
> Thanks for taking the time to help.
>
> > The "Welcome"-Tab
> >
> > Aims at giving a quick introduction to the Forrest-project the
> > software and its goals and capabilities.
> >
> > Provides intro on an executive summary level plus examples to quickly
> > get the idea what can be done with Forrest.
> >
> > The "Developers"-Tab:
> >
> > This used to be the Project tab and that pretty well summarized the
> > content I found under it: All materials that are needed to participate
> in
> > Forrest as a project. Specifically
> >
> > - in which ways I can participate
> > - where to find the tools and infrastructure needed to participate
> > - and how to go about certain tasks
> >
> > I subdivided these tasks in a way that tries to minimize access
> > time to information while categorizing it logically by the kind of
> > info that can be found in it.
> >
> > The idea being that I didn't have to dig through all documentation to
> > find all "best practice" documents or references to resources.
> >
> > - Getting involved explains the different ways of participating in the
> > project and yes - Tim is right - this could be the tab-heading
> > really if we don't go back to "Project" (see comments below).
> >
> > Creating a separate sub-section "Project" came out of renaming the
> > tab from "Project" to "developers". It did not make a lot
> > of sense to me at the time but since I was busy with other things
> > ...
>
> In the previous thread, Ross and i had strong opinions
> about not making a distinction between "us and them".
> We are all "developers". Some of us (mainly the committers)
> make extra effort to do the tasks that keep the project
> flowing. I have not yet heard any justification for making
> a distinction. In fact i think that it would be dangerous
> for the project health.
>
> See the last section of:
> Re: Document restructuring - confused
> http://thread.gmane.org/gmane.text.xml.forrest.devel/21380/focus=21380
> and the subsequent messages.
>
> The "Developers" tab includes a few documents under
> the sub-section "Project". I reckon that these should
> be moved up to the "Getting involved" section.
I agree with this.
>
> > - Resources and Infrastructure lists the tools and infrastructure
> > available for people working for the project.
>
> I think that it is way more that just that little group.
> Developers want to participate in the mailing lists, and
> want to search and add to the Issue Tracker, etc.
>
> > ...This could be a
> > subheading to "Getting involved" but since it is needed quite often
> > I left it at the top level to make it easier to find.
>
> Perhaps we should merge these few resources into the
> top-level section and rename it from "Getting involved"
> to "Resources and Infrastructure" (or a better name).
Along with merging the 'project' section, if we were to merge this to the
Top level 'Getting Involved' section , there would be 14 links then. I
Still think there is a use for 'Resources' (rather than the longer name) in
Which 'Mailing Lists' 'Browse SVN' 'Zone Testbed' could remain. The
remaining two links to 'Gump Integration' and 'Issue Management' could be
Moved up as I don't see these as 'resources'.
Two things I noticed whilst looking at this - there are 'two' links to the
Mailing Lists, is this on purpose ?
The second is a 'todo' query I'll post seperatly.
Gav...
>
> -David
>
> > - Best practices and procedures
> > This section is the howto-part of the project manual. And again I
> > wanted these to be visible so that people realize that there are
> > guidelines before they start working ...
> >
> > In reply to Tim's comments:
> >
> > > "Resources and Infrastructure" - Resources is way too ambigious to be
> > > a part of a navigation scheme I think.
> >
> > Part of my motivation for creating this section is
> > that I wanted compact directory of all the tools, resources and
> > infrastruture urls in one place.
> >
> > Perhaps you can suggest a better name for this.
> >
> > > Infrastructure also doesn't
> > > carry much meaning when I think of an open source project.
> >
> > To me infrastructure is quote "the underlying foundation or basic
> > framework (as of a system or organization)" and refers to all the
> > tools and resources that allow us to work together. Can you explain
> > why it doesn't carry meaning in an OS project? What would be a better
> > term.
> >
> > > It turns
> > > out that likely what most folks are looking for is really under here
> > > (mailing lists, code access, and issue reporting).
> >
> >
> > Is it really? And if so, do we really want to encourage that. Wouldn't
> > it make sense to read about how to get involved and understand the
> > best pratices before one actually using the issue tracker.
> >
> > I agree that later on this might be the most often used category
> > (that's why I didn't make it a sub section of "getting involved".
> >
> > Besides: I very much favour multiple ways of accessing the same
> > information. Such as links in the "How to get started"-section that
> > links to the user-mailinglist and encourages people to subscribe to it.
> >
> > > "Best Practices and Procedures" - Again, I think it doesn't carry
> > > enough common concrete meaning to be a part of a navigation scheme.
> > > Do people know what they can expect to find when they click this?
> >
> > It thought "Best practices" in the context of "Project" carries a lot of
> > meaning. And I wanted this to be top level to be easily found.
> >
> > > "Project" - This is currently buried under "Getting Involveld". It
> > > seems to me that there is some good information that should be given a
> > > better spot.
> >
> > Yes I agree. Renaming "Project" to "Developers" has created a
> > unfortunate situation and made the project specific document a bit
> > homeless. Is it too late to argue against the renaming of the tab?
> >
> > > If not,
> > > maybe we could kick around some alternative schemes on the mail list
> > > to improve it?
> >
> > Please do, I'm curious to see what you come up with.
> >
> > In reply to Ross:
> >
> > > Your not the only one. I can't find anything either (see my previous
> > > post on this topic). Ferdinand said he was had not completed what he
> > > wanted to do, but that was quite some time ago now.
> >
> > Actually I was referring to the "Version Docs" tab as being
> > incomplete. And afair mentioned that the available docs did not
> > really match the structure that our grammar suggested because the
> > often mix instructional and background info. Anybody could fix that by
> > rewriting and spitting up certain documents.
> >
> > hth
> > Ferdinand
> >
> >
> >
> >
> >
> >
> >
> >
> >
> > Before I do, the Developers-Tab aka "Project" is not part of the
> > unfinished business really. The "Versioned docs" is because most of
> > our docs cross the boundary between instructional and background
> > documentation and did not fit the categories that aimed at separating
> > the how-tos from back
> >
> >
> >
> >
> > --
> > Ferdinand Soethe
>
>
> --
> No virus found in this incoming message.
> Checked by AVG Free Edition.
> Version: 7.1.394 / Virus Database: 268.10.8/413 - Release Date: 8/8/2006
Re: Site-author organization
Posted by David Crossley <cr...@apache.org>.
Ferdinand Soethe wrote:
>
> Sorry for being so quiet for long time. Had and still have some
> pressing personal issues to attend to. But I'm still reading and I'll
> try to explain what I had in mind when I started this restructuring:
Thanks for taking the time to help.
> The "Welcome"-Tab
>
> Aims at giving a quick introduction to the Forrest-project the
> software and its goals and capabilities.
>
> Provides intro on an executive summary level plus examples to quickly
> get the idea what can be done with Forrest.
>
> The "Developers"-Tab:
>
> This used to be the Project tab and that pretty well summarized the
> content I found under it: All materials that are needed to participate in
> Forrest as a project. Specifically
>
> - in which ways I can participate
> - where to find the tools and infrastructure needed to participate
> - and how to go about certain tasks
>
> I subdivided these tasks in a way that tries to minimize access
> time to information while categorizing it logically by the kind of
> info that can be found in it.
>
> The idea being that I didn't have to dig through all documentation to
> find all "best practice" documents or references to resources.
>
> - Getting involved explains the different ways of participating in the
> project and yes - Tim is right - this could be the tab-heading
> really if we don't go back to "Project" (see comments below).
>
> Creating a separate sub-section "Project" came out of renaming the
> tab from "Project" to "developers". It did not make a lot
> of sense to me at the time but since I was busy with other things
> ...
In the previous thread, Ross and i had strong opinions
about not making a distinction between "us and them".
We are all "developers". Some of us (mainly the committers)
make extra effort to do the tasks that keep the project
flowing. I have not yet heard any justification for making
a distinction. In fact i think that it would be dangerous
for the project health.
See the last section of:
Re: Document restructuring - confused
http://thread.gmane.org/gmane.text.xml.forrest.devel/21380/focus=21380
and the subsequent messages.
The "Developers" tab includes a few documents under
the sub-section "Project". I reckon that these should
be moved up to the "Getting involved" section.
> - Resources and Infrastructure lists the tools and infrastructure
> available for people working for the project.
I think that it is way more that just that little group.
Developers want to participate in the mailing lists, and
want to search and add to the Issue Tracker, etc.
> ...This could be a
> subheading to "Getting involved" but since it is needed quite often
> I left it at the top level to make it easier to find.
Perhaps we should merge these few resources into the
top-level section and rename it from "Getting involved"
to "Resources and Infrastructure" (or a better name).
-David
> - Best practices and procedures
> This section is the howto-part of the project manual. And again I
> wanted these to be visible so that people realize that there are
> guidelines before they start working ...
>
> In reply to Tim's comments:
>
> > "Resources and Infrastructure" - Resources is way too ambigious to be
> > a part of a navigation scheme I think.
>
> Part of my motivation for creating this section is
> that I wanted compact directory of all the tools, resources and
> infrastruture urls in one place.
>
> Perhaps you can suggest a better name for this.
>
> > Infrastructure also doesn't
> > carry much meaning when I think of an open source project.
>
> To me infrastructure is quote "the underlying foundation or basic
> framework (as of a system or organization)" and refers to all the
> tools and resources that allow us to work together. Can you explain
> why it doesn't carry meaning in an OS project? What would be a better
> term.
>
> > It turns
> > out that likely what most folks are looking for is really under here
> > (mailing lists, code access, and issue reporting).
>
>
> Is it really? And if so, do we really want to encourage that. Wouldn't
> it make sense to read about how to get involved and understand the
> best pratices before one actually using the issue tracker.
>
> I agree that later on this might be the most often used category
> (that's why I didn't make it a sub section of "getting involved".
>
> Besides: I very much favour multiple ways of accessing the same
> information. Such as links in the "How to get started"-section that
> links to the user-mailinglist and encourages people to subscribe to it.
>
> > "Best Practices and Procedures" - Again, I think it doesn't carry
> > enough common concrete meaning to be a part of a navigation scheme.
> > Do people know what they can expect to find when they click this?
>
> It thought "Best practices" in the context of "Project" carries a lot of
> meaning. And I wanted this to be top level to be easily found.
>
> > "Project" - This is currently buried under "Getting Involveld". It
> > seems to me that there is some good information that should be given a
> > better spot.
>
> Yes I agree. Renaming "Project" to "Developers" has created a
> unfortunate situation and made the project specific document a bit
> homeless. Is it too late to argue against the renaming of the tab?
>
> > If not,
> > maybe we could kick around some alternative schemes on the mail list
> > to improve it?
>
> Please do, I'm curious to see what you come up with.
>
> In reply to Ross:
>
> > Your not the only one. I can't find anything either (see my previous
> > post on this topic). Ferdinand said he was had not completed what he
> > wanted to do, but that was quite some time ago now.
>
> Actually I was referring to the "Version Docs" tab as being
> incomplete. And afair mentioned that the available docs did not
> really match the structure that our grammar suggested because the
> often mix instructional and background info. Anybody could fix that by
> rewriting and spitting up certain documents.
>
> hth
> Ferdinand
>
>
>
>
>
>
>
>
>
> Before I do, the Developers-Tab aka "Project" is not part of the
> unfinished business really. The "Versioned docs" is because most of
> our docs cross the boundary between instructional and background
> documentation and did not fit the categories that aimed at separating
> the how-tos from back
>
>
>
>
> --
> Ferdinand Soethe
Re: Site-author organization
Posted by Ferdinand Soethe <fe...@apache.org>.
Sorry for being so quiet for long time. Had and still have some
pressing personal issues to attend to. But I'm still reading and I'll
try to explain what I had in mind when I started this restructuring:
The "Welcome"-Tab
Aims at giving a quick introduction to the Forrest-project the
software and its goals and capabilities.
Provides intro on an executive summary level plus examples to quickly
get the idea what can be done with Forrest.
The "Developers"-Tab:
This used to be the Project tab and that pretty well summarized the
content I found under it: All materials that are needed to participate in
Forrest as a project. Specifically
- in which ways I can participate
- where to find the tools and infrastructure needed to participate
- and how to go about certain tasks
I subdivided these tasks in a way that tries to minimize access
time to information while categorizing it logically by the kind of
info that can be found in it.
The idea being that I didn't have to dig through all documentation to
find all "best practice" documents or references to resources.
- Getting involved explains the different ways of participating in the
project and yes - Tim is right - this could be the tab-heading
really if we don't go back to "Project" (see comments below).
Creating a separate sub-section "Project" came out of renaming the
tab from "Project" to "developers". It did not make a lot
of sense to me at the time but since I was busy with other things
...
- Resources and Infrastructure lists the tools and infrastructure
available for people working for the project. This could be a
subheading to "Getting involved" but since it is needed quite often
I left it at the top level to make it easier to find.
- Best practices and procedures
This section is the howto-part of the project manual. And again I
wanted these to be visible so that people realize that there are
guidelines before they start working ...
In reply to Tim's comments:
> "Resources and Infrastructure" - Resources is way too ambigious to be
> a part of a navigation scheme I think.
Part of my motivation for creating this section is
that I wanted compact directory of all the tools, resources and
infrastruture urls in one place.
Perhaps you can suggest a better name for this.
> Infrastructure also doesn't
> carry much meaning when I think of an open source project.
To me infrastructure is quote "the underlying foundation or basic
framework (as of a system or organization)" and refers to all the
tools and resources that allow us to work together. Can you explain
why it doesn't carry meaning in an OS project? What would be a better
term.
> It turns
> out that likely what most folks are looking for is really under here
> (mailing lists, code access, and issue reporting).
Is it really? And if so, do we really want to encourage that. Wouldn't
it make sense to read about how to get involved and understand the
best pratices before one actually using the issue tracker.
I agree that later on this might be the most often used category
(that's why I didn't make it a sub section of "getting involved".
Besides: I very much favour multiple ways of accessing the same
information. Such as links in the "How to get started"-section that
links to the user-mailinglist and encourages people to subscribe to it.
> "Best Practices and Procedures" - Again, I think it doesn't carry
> enough common concrete meaning to be a part of a navigation scheme.
> Do people know what they can expect to find when they click this?
It thought "Best practices" in the context of "Project" carries a lot of
meaning. And I wanted this to be top level to be easily found.
> "Project" - This is currently buried under "Getting Involveld". It
> seems to me that there is some good information that should be given a
> better spot.
Yes I agree. Renaming "Project" to "Developers" has created a
unfortunate situation and made the project specific document a bit
homeless. Is it too late to argue against the renaming of the tab?
> If not,
> maybe we could kick around some alternative schemes on the mail list
> to improve it?
Please do, I'm curious to see what you come up with.
In reply to Ross:
> Your not the only one. I can't find anything either (see my previous
> post on this topic). Ferdinand said he was had not completed what he
> wanted to do, but that was quite some time ago now.
Actually I was referring to the "Version Docs" tab as being
incomplete. And afair mentioned that the available docs did not
really match the structure that our grammar suggested because the
often mix instructional and background info. Anybody could fix that by
rewriting and spitting up certain documents.
hth
Ferdinand
Before I do, the Developers-Tab aka "Project" is not part of the
unfinished business really. The "Versioned docs" is because most of
our docs cross the boundary between instructional and background
documentation and did not fit the categories that aimed at separating
the how-tos from back
--
Ferdinand Soethe