Home » Eclipse Projects » Eclipse Titan » TITAN manuals are hard to find / not publicly searchable/indexed
| TITAN manuals are hard to find / not publicly searchable/indexed [message #1790623] |
Wed, 13 June 2018 16:17  |
|
This has actually come up several times in the context of the Osmocom project: People don't find the manuals easily, and even if one mentions "the TITAN referenceguide.pdf", it still is not found easily.
The reason for this (IMHO) is the fact that they are only available as PDF files inside a ZIP file (such as https://www.eclipse.org/downloads/download.php?file=/titan/TitanDocuments_6_3_0.zip) , which means they are not indexed anywhere, or at least not by the search machines I know, like google, ixquick, startpage, bing, etc.
If you search for , you will get links to a Nissan Titan, and to a GeForce GTX Titan, to titan metal fabricators reference guide, and only further down the road you can find a link to https://www.eclipse.org/forums/index.php/t/1083594
which also only states "See clause 4.22 of the Titan Ref. guide referenceguide.pdf", but is still not a link to the actual manual.
A search for eclipse titan reference guide
I think this is a serious problem. I've seen at least two people who have been working with TITAN for months now, who were not aware that those manuals exist and where to find them.
The situations is further aggravated by the fact that:
* the Debian packages for TITAN don't install them to /usr/share/doc, where normally you would expect documentation
* the Debian packages also don't have a separate eclipse-titan-doc sub-package.
(I'll file the above two to the Debian bug tracker)
I really think it would be extremely useful if the manuals were published in a form that resulted in automatic indexing bythe major search engines. I guess all that's needed is to put them somewhere on the web, and create some links to the PDF files, so they can be found by the spiders.
There is great documentation that is part of TITAN, it's just very carefully hidden from the web. Please consider changing that.
Thanks for your consideration!
|
|
|
| Re: TITAN manuals are hard to find / not publicly searchable/indexed [message #1790635 is a reply to message #1790623] |
Wed, 13 June 2018 17:55  |
|
Hi Harald,
thank you for pointing that out; I will follow your advice regarding the compressed file vs. indexable presence.
BTW, Titan documentation is packed in every downloadable binary package and also published in github, together with the code, but it appears that this is not sufficient.
Packing the documentation together with the binary/source tries to keep consistency, as each release has a -to a lesser or greater degree - different version of the guides , and it can be very confusing to have the sync broken between the release version and the documentation version.
However, I'll try to make the trail of breadcrumbs leading to them more visible.
Best regards
Elemer
|
|
|
| Re: TITAN manuals are hard to find / not publicly searchable/indexed [message #1790637 is a reply to message #1790635] |
Wed, 13 June 2018 18:37 |
|
Elemer Lelik wrote on Wed, 13 June 2018 19:55
thank you for pointing that out; I will follow your advice regarding the compressed file vs. indexable presence.
Thanks!
Elemer Lelik wrote on Wed, 13 June 2018 19:55
BTW, Titan documentation is packed in every downloadable binary package
I noticed this. However, I would argue that a typical (experienced) Linux user wouldn't install binary packages that are distributed as .tar.gz and that bypass the package manager, but install a package for his distribution. This takes advantage of proper dependency management, automatic updates, etc. Luckily, as Debian users, there are packages. However, those packages appear to be missing the documentation, for which I've filed https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=901463
off-topic: It would be great if the binary releases of eclipse titan were packaged as .deb / .rpm packages for the various distributions you support. OBS (OpenSuSE Build Service) is a great tool how one can automatically build distribution-specific packages for a whole range of distributions and architectures, we use this e.g. for the osmocom nightly and released builds. You can see the full matrix of the package builds at https://build.opensuse.org/project/monitor/network:osmocom:latest
Elemer Lelik wrote on Wed, 13 June 2018 19:55
and also published in github, together with the code, but it appears that this is not sufficient.
it doesn't even appear obvious to me, and I've extensively worked with TITAN during the last 12 months. Among the many cloned titan.* git repositories on my computer, I cannot see the manuals. For example, titan.core has a doc/ directory, but that's not for the reference guides, it seems. Having the documentation in that repository would mean that you could check-out a given git tag, and you'd have the corresponding docs.
Oh, wait, there are actualy .doc files in the git repo in the "usrguide" path. I was just using various 'find' commands for the PDF files. Sorry ;)
Elemer Lelik wrote on Wed, 13 June 2018 19:55
Packing the documentation together with the binary/source tries to keep consistency, as each release has a -to a lesser or greater degree - different version of the guides , and it can be very confusing to have the sync broken between the release version and the documentation version.
Full acknowledgement. I guess the trigger of our "problem" is that we all use the Debian packages in the Osmocom team, and those don't include it for some reason.
Elemer Lelik wrote on Wed, 13 June 2018 19:55
However, I'll try to make the trail of breadcrumbs leading to them more visible.
Thanks. I do think it's worth the effort, paticularly to make sure that major search engines index the contents. You might have the answer to the problem in some local .doc file in a git repo, but then people still use Google+Co to find answers (and then don't find them).
btw: You were mentioning converting the documentation from 'legacy document formats'. If you haven't yet made a decision, I would personally suggest having a look at using asciidoc as a source format. For some examples, see http://git.osmocom.org/osmo-gsm-manuals/tree/ for the soruce code and http://ftp.osmocom.org/docs/latest/ for the rendered PDF files.
It's great that you can e.g. use dotty/graphviz + mscgen syntax for having in-line graph and message sequence charts in the documentation - and all that in very human-readable and -writable ASCII text. See e.g. http://ftp.osmocom.org/docs/latest/osmobts-abis.pdf for the message sequenc charts or Section 4.2.2.1 of http://ftp.osmocom.org/docs/latest/osmobsc-usermanual.pdf for the dotty/graphviz integration.
The ASCII source code makes for very readable change logs, and you can handle contributions to the documentation just like you handle code changes, with review in gerrit, ... - have a look at e.g. http://git.osmocom.org/osmo-gsm-manuals/commit/?id=908b83836674545befb20ad13ac37262ac1756c1
If you think that would have a future, I could give it a try and do an asciidoc version of the userguide.pdf as a small contribution to TITAN. It's smaller than referenceguide.pdf, and shouldn't be too much work...
Regards,
Harald
|
|
| |
| Re: TITAN manuals are hard to find / not publicly searchable/indexed [message #1790727 is a reply to message #1790667] |
Fri, 15 June 2018 06:46 |
|
Hi Harald,
it's exactly asciidoc we have started working with;
expectedly by the beginning of July we will finish with the protocol modules/test ports etc.
Titan documentation will follow soon after.
First ( by 6th of July) we will release 6.4.0 as is and then we will migrate to the asciidoc documentation.
I will also try to find a solution for Debian.
Best regards
Elemer
|
|
|
Goto Forum:
Current Time: Thu Apr 25 18:02:50 GMT 2024
Powered by FUDForum. Page generated in 5.04046 seconds |
] 
Search
Help
Register
Login
Home
