[Fedora-electronic-lab] User documentation (was Re:Dead Upstream what should we do ?)

[Chitlesh GOORAH]

On Fri, Dec 4, 2009 at 7:50 PM, Shakthi Kannan wrote:
>  Just want to discuss this further as our list of packages is growing
> day-by-day: 
Yes userguides are currently one of your weaknesses. Let's create
another thread for this as we definitely got to find a suitable
solution for the long term.

>  1. Whatever documentation made for a particular software can be
> pushed
>  upstream, so we keep track of only one set of sources. We will do
>  documentation in LaTeX or DocBook, so we abstract content with
>  presentation, and it will greatly help us in the long run. 
+1 documentation should be pushed to upstream

I would tend to opt for LaTex as most of our upstream developers like
to keep their documentation in text format.
Having that said, what should we do for other tools which upstream
ships loads of documentation in OOo formats e.g kicad-doc ?

As we know Latex gives one the opportunity to create documents in any
type of format e.g pdf, dvi, ps ...
If we are to ship the same contents in different formats, we should
also bundle all the plugins for these formats. In FEL-12, I didn't
think about this and by default (on the livedvd) one cannot read .dvi
files with evince, because I missed the package evince-dvi on the
livedvd (sorry by the way :) ). The more we add such type of
dependencies to the livedvd the more
  * time we have to allocate for the livedvd's testing
  * time we have to allocate for package reviews
  * the size the livedvd will be.
  * the more dependencies they will pull.
So here a decision should be made. If it was for me, pdf format is
enough. What do you think ?

>  2. In Yelp, we can provide links to all relevant installed package
>  documentation? If that can be done, it will only be linking to the
>  respective files? or else we will need something similar in the lines
>  of .desktop files that can simply pin-point to where the doc/, man/,
>  info/ pages for each software/tool that is shipped, and are
>  independent of desktop environments. 
I have no idea if linking to specific files is possible.
In the wiki pages I'm editing on
https://fedorahosted.org/fedora-electronic-lab/wiki/Digital, I'm
pointing to these type of commands :

$ man XXXXX
or
$ rpm -qd XXXXXX

example in : https://fedorahosted.org/fedora-electronic-lab/wiki/Digital/iverilog

Pointing to specific files would be great for the user, but hard on
us. Each time upstream add/remove docs, the packager will have to
update this yelp correctly.


>  3. We will also need to provide documentation on suggested workflows
>  with various tools that are shipped, so people can follow it. 
This is coupled with your #2. Either we do it in
* latex directly and output one big PDF which we can package
separately so that it can be shipped on the livedvd and be updated as
any other package, ( we could possibly add the release notes and the
flyer in that package as well)
* or in yelp as in #2.

If in #1, we choose latex, I would favour latex here too. What do you think ?
"Design flows" is one of FEL's strengths. It would be difficult to
push this upstream as many tools of different upstreams will fall in
different flows. Hence we have to maintain it ourselves in our git.
However we have to ensure it can also easily available so that other
distributions can use that "Design flows" doc as reference.


Chitlesh

[Shakthi Kannan]

Hi,

--- On Sat, Dec 5, 2009 at 1:36 AM, Chitlesh GOORAH
<chitlesh(a)fedoraproject.org&gt; wrote:
| I would tend to opt for LaTex as most of our upstream developers like
| to keep their documentation in text format.
\--

We agree to use this for all our documentation needs.

---
| Having that said, what should we do for other tools which upstream
| ships loads of documentation in OOo formats e.g kicad-doc ?
\--

If we can export the OOo formats to LaTeX directly or through
intermediate formats like DocBook, we can maintain consistency.

---
| So here a decision should be made. If it was for me, pdf format is
| enough.
\--

Agreed.

---
| Pointing to specific files would be great for the user, but hard on
| us. Each time upstream add/remove docs, the packager will have to
| update this yelp correctly.
\--

Can this be done in the RPM packaging process?

We know the .spec file mentions the -doc files. If we are able to list
and put the location of all these -doc files for a package in a text
file, say package.guide, similar to a .desktop file, an application
can read all these package.guide files from a single directory (say,
/usr/share/guide/*.guide) and show it to the user.

This .guide file is important because it abstracts location of files
from the GUI help manager, so we can use it across different desktop
environments.

As long as it doesn't violate FHS, this will provide the user with
available documentation. FESCo needs to look at it? Maybe, if we
provide a prototype using FEL, we can get feedback and others' point
of view? Just a thought.

---
| "Design flows" is one of FEL's strengths. It would be difficult to
| push this upstream as many tools of different upstreams will fall in
| different flows. Hence we have to maintain it ourselves in our git.
\--

Yes, we can maintain it as you have mentioned.

SK

-- 
Shakthi Kannan
http://www.shakthimaan.com

[Chitlesh GOORAH]

On Sat, Dec 5, 2009 at 6:31 AM, Shakthi Kannan  wrote:
>  Can this be done in the RPM packaging process?
>
>  We know the .spec file mentions the -doc files. If we are able to list
>  and put the location of all these -doc files for a package in a text
>  file, say package.guide, similar to a .desktop file, an application
>  can read all these package.guide files from a single directory (say,
>  /usr/share/guide/*.guide) and show it to the user. 
Hello

Yes, we can. It's up to us to maintain such things. But listing all
the doc files off a package will give a lot of outputs, userguides,
example directories containing a lot of files etc.

# case 1

So at first we need to setup a simple guideline for packaging the docs
and work with upstream to improve the quality of doc distribution.

Let's say to begin with we ensure that in the doc directory
/usr/share/doc/NAME-VERSION/ we have these files:
 * userguide.pdf
 * examples/ directory
   * example1
   * example2

hence we can easily sketch a minor script to look for those items and
flush its output into a latex file.

# case 2

Start writing a userguide in latex. Let's say, in the PCB section, if
we point to pcb.pdf coming with the package, we can exact a script
against our latex file which will automatically go and search for the
exact file path and create a link on the "pcb.pdf" text on our latex
file (using the url latex package).

My thoughts:
Case 1 : we have to work very hard to ensure consistency with all the
FEL packages. Time would be a major concern for me.
Case 2 : one central location for all the docs (our latex file) and
for every release, we execute the script to update and create a pdf.

What do you think ?

Chitlesh