Hi Romain, 1) tagging is a good idea to support an additional way of finding "the right" help page.
2) Additionally I would like generated links to the API reference in every documentation page. API links could be specially marked up (like with a small API icon), so user has a chance to separate between normal help page links and API links. Example: http://savonet.sourceforge.net/doc-1.0.0/advanced.html "You can find more details on how to configure the server in the documentation <http://savonet.sourceforge.net/doc-1.0.0/help.html#settings> of the settings key |server|, in particular |server.telnet| for the TCP interface and |server.socket| for the Unix interface. Liquidsoap also embeds some documentation <http://savonet.sourceforge.net/doc-1.0.0/help.html#server> about the available server commands." "server", "server.telnet" and "server.socket" could point to the API reference. 3) Chapter titles: Generally there has been much improvement. I know its difficult to separate technical view and user view, from user perspective I prefer easily to understand usecase based documentation like "control liquidsoap using telnet" instead of "interaction with the server". Unfortunately I am not good with this by myself, but I hope you understand what I mean :-) Another example: "Interaction with the Harbor <http://savonet.sourceforge.net/doc-1.0.0/harbor_http.html>:" a user has to read the byline to understand that this is about the HTTP server - and then to detect "great, they support a HTTP server!". 4) chapter structure A newbe does not know that both "server interaction" and default config/log directories are covered by "Advanced techniques". Vice versa if I look espacially for "server interaction" at documentation.html I would not expect it at the "advanced" point. Additionally there is a separate chapter "Using in production <http://savonet.sourceforge.net/doc-1.0.0/in_production.html>:" with the same content of /etc,/log docs. In general I have some difficulties to separate FAQ entries from cookbook entries (where do I have to look at). If I look for a special topic like "playlist", I will find some information at the "cookbook" at "files" then after some different recepts at "Force a file/playlist to be played at least every XX minutes" and additionally some general information at "quick start". From user perspective there could be a single chapter "playlists" which explains everything for "playlists" with examples and usecases, and so on. In this case tagging would not bring an advantage, providing a set of referenced pages is the same as google does. Eventually tagging subchapters/or even paragraphs and aggregating them into a single page could help, but a single "playlist" chapter would provide more quality for me. Today a new user will have to read through almost all pages to get a picture of if liquidsoap is the right software for what one is searching for. Because of complexity of the subject I am not sure if this can be solved at all. Maybe tagging and API references can help to find the right solution. From my view documentation.html chapter index could be changed a bit from technical view towards user view, today it's the base If I am looking for help. Thanks again for what you are doing for our community radio! BR, Peter Am 24.02.2012 22:04, schrieb Romain Beauxis: > 2012/2/24 Martin Hamant<[email protected]>: >> Okay ! >> >> I didn't know it is possible to set a PA source in the device parameter ! >> Romain, David : What about adding this to the documentation ? >> >> I can take care of writing a little snippet about this in the >> sourcefabric wiki > Sure, please do :-) > > However, that brings a question I've been wondering about for a while > now.. What do you guys think of the current documentation? > > I mean, I think we cover quite a lot, with or without typos (mostly by > me) and mostly understandable. What I am worried about is the overall > organization and how to make sure that the average user finds the most > relevant page for him as quick as possible.. > > Thus, I'm wondering: what has been your experience guys when browsing > the documentation? Would you have suggestions regarding its > organization? > > I personally wonder about a system where documentation pages are > tagged/indexed by some keywords and a free search which would > redirect/show resulting pages, much like the API operator search box.. > > Romain > ------------------------------------------------------------------------------ Virtualization & Cloud Management Using Capacity Planning Cloud computing makes use of virtualization - but cloud computing also focuses on allowing computing to be delivered as a service. http://www.accelacomm.com/jaw/sfnl/114/51521223/ _______________________________________________ Savonet-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/savonet-users
