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. Offline use is presumably only to be expected
if the user has installed on their local machine. 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.
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.
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.
It would also be nice to be able to have an easy way to switch between
versions like the [[TranslatedPages]] macro gives for translations. We
could also consider whether it is appropriate for the documentation to
be moved to a different location altogether.
There are other rough edges to the idea, depending on how we want it
implemented. For instance, some guide pages currently use macros to
provide information relevant to a local installation. If we leave those
pages as part of the local installation, referring to them from the
documentation site is not currently likely to work.
Anyway, I am happy that the idea makes good sense and we should be able
to make it work.
Cheers,
Gary
