[squid-dev] [RFC] Wiki sections redesign

[Alex Rousskov]

On 08/20/2015 10:52 PM, Amos Jeffries wrote:

> One thing that is standing out is that placing wishlist designs under
> Features/ was a bad idea. It makes it very hard to identify those
> wishlist entries from actually available, in-use or has-been features.

Each Feature has a Status attribute that is supposed to describe the
feature state. If that attribute does not work well (for whatever
reason), then a dedicated directory is unlikely to work well either. A
Status attribute can reflect more than two states and does not require
changing feature URLs, so it feels like the attribute is a better
solution than a dedicated directory, even if it does not work well.


> With some of us (me included) one way or another keeping feature plans
> semi-secret until the last moment the whole concept behind Priority
> levels has fallen on its face. No way to help each other make progress
> on high priority projects if all we see is rough mention of a project
> then final audit patches at the end.

I really doubt things [not] written on wiki prevent us from helping each
other.

As for the Priority field itself, it can only be interpreted/compared
correctly in a context of Features created by the same developer, so its
Project-wide utility cannot be high indeed. I try to set it accurately
on my pages, but (as anything on wiki) it is often stale, and I do not
know whether anybody has been actually using that information.

Your Priority side note seems to be unrelated to your Feature placement
proposal.


> * I propose adding a section "Blueprints/" or "Wishlist/" to contain
> what is now the Features pages for projects which are either just
> describing wishlist outlines, or developer-only projects and not
> actually user visible features of Squid.
>  To be moved to Features/ when the page is re-written with final
> end-user feature documentation.

I believe Status attribute is a better approach for the reasons stated
in the first paragraph of my response, but if others think otherwise, I
will just follow their lead when creating new pages. This is not
important IMO.


> I also re-propose an old suggestion:
> 
> * That we make the ProgrammerGuide/ (or "Developers/" ?) section
> actually the how-to documents for developers instead of just an outdated
> FAQ copy on how squid-2 ('ish) code works.

There is some Squid3-relevant stuff in there (e.g., ClientStreams), but
I do not know whether anybody is actually using it. IMHO, if you do not
delete the old stuff, you can add whatever new documentation you think
is useful, including how-to documents for developers.


HTH,

Alex.