On 5/28/13, Gary Martin <[email protected]> wrote: > On 29/05/13 01:00, Olemis Lang wrote: >> On 5/28/13, Joachim Dreimann <[email protected]> wrote: >>> I would like to challenge the assumption that we need to ship the >>> help/guide wiki pages with Bloodhound by default. >>> >>> I believe our users and us are better served by adding local >>> documentation >>> as an optional plug-in. >>> >>> In any default installation of Bloodhound there should be only a single >>> "What you need to know" page of documentation, short enough to be >>> printed >>> out on a single A4 sheet of paper. >>> >>> The recent conversations on where documentation should live were the >>> trigger to me thinking about this [1]. From a community perspective this >>> change would bring more people back to our site, which must be a good >>> thing. From a user perspective they're guaranteed to get the latest >>> documentation for their version. For example when better documentation >>> on >>> 0.5 is available after the release of 0.5, they wouldn't find this in >>> their >>> locally installed version. >>> >> There are only two remarks I'd like to mention : >> >> 1. some users might be offline > > I suspect that Joe has covered this point pretty well unless I > misunderstand your point.
Like I just said , IMO it's a good idea . I was just adding in a side note that e.g. it's very cool to have Python , Genshi , Trac , Routes, ... docs in your PC for quick access at development time ; though these might be distributed separately ;) > Offline use is presumably only to be expected > if the user has installed on their local machine. FWIW , I use these relatively often when programming ... thus confirming the initial statement . > If this is the > expectation or if there are otherwise any deliberate restrictions on > access other than to the local bloodhound server then the optional local > documentation plugin should be the appropriate way to go. > Maybe a distributing docs separately after packaging might be another (better?) choice > Meanwhile, the suggestion of a single page cheat-sheet of essential > documentation provides some protection in case there are temporary > problems accessing the main documentation. > Agreed my side since the beginning ;) >> 2. we'll need some sort of versioning scheme in the wiki. >> my point is that following that approach , if user is running >> x.y and latest version is x.y+1 then docs for that particular >> version should be expected ... isn't it ? > > Again, I think Joe is alluding to that point in his discussion. > Sure. After confirming my suspicion I'd just suggest to take a look into the structure of Genshi docs including 1. versioning 2. user vs API docs (<= that's another point to consider IMHO ;) http://genshi.edgewall.org/ -- Regards, Olemis.
