Bug #578

Merge user and "installation" manual

Added by Alexandre Quessy almost 3 years ago. Updated 10 months ago.

Status:Closed Start date:
Priority:High Due date:
Assignee:Alexandre Quessy % Done:

0%
Category:documentation Spent time: 2.00 hours
Target version:1.0 Estimated time:20.00 hours
Resolution: Version:0.5.11
Trac ticket ID:578

Description

Rationale: Once Scenic is installed, the installation manual is useless.

If it's not really an installation manual, then it should be merged with the user manual, since it's a user manual that is specific to the audio/video devices.

That will avoid duplication of the information.

Debian's doc-base system expects one and only one manual per package. We are splitting to doc into the scenic-doc package. That would be a lot simpler if there was just one manual.

History

#1
Updated by Alexandre Quessy almost 3 years ago

This is actually a blocker since we need to get decided on this point prior to get the Debian packaging done.

#2
Updated by Alexandre Quessy about 1 year ago

  • Assignee changed from Simon Piette to Andrew Kozloski
  • Priority changed from High to Low

#3
Updated by Andrew Kozloski about 1 year ago

  • % Done changed from 0 to 100

The merge is completed. There remains a good deal of work to do in getting the documentation correct, however. Most or all of the images are missing and some pages are not displaying as html rather than being formatted by the html they contain.

#4
Updated by Andrew Kozloski about 1 year ago

Andrew Kozloski a écrit :

The merge is completed. There remains a good deal of work to do in getting the documentation correct, however. Most or all of the images are missing and some pages are displaying the html on the page rather than being formatted by the html they contain.

#5
Updated by Alexandre Quessy 12 months ago

  • Target version changed from 0.6.3 to 1.0

Here are some explanations on exactly what to do.

Scenic's manual is in the docbook format. It is currently split into two manuals: the installation manual, and the user manual. They are located in scenic's Git repository in the doc/docbook directory. The manual is primarily written in English, and has been translated to French. That's why there are an "en" and a "fr" directories.

The manuals can be viewed with the "yelp" command-line utility.

$ yelp user-manual.xml $ yelp installation-manual.xml

In my opinion, these two manuals should be merged in a single one. There is a lot of contents that is duplicated. Also, plugin the audio and video devices is not typically an "installation" activity. The users also setup their hardware. Such a distinction between "users" and "installers" brings a whole world of confusion. What do you think?

Merging those two manuals implies moving files around so that they are in the same directory. (the "user" and the "installation" directories should be merged) Also, it implied merging the xml files so that the text still makes sense. Finally, it requires the Makefile.am files to be updated so that the .xml files are installed properly when Scenic is. This requires some training and or help from a software developer.

The Docbook markup is rather easy to use. It is based on XML. Editing the XML files should be done with a basic text editor. (such as Gedit)

References:

#6
Updated by Alexandre Quessy 12 months ago

Of course, both the English and the French version should be merged.

#7
Updated by Alexandre Quessy 12 months ago

More explicitely, I mean:
  • merge doc/docbook/en/user.xml and doc/docbook/en/installation.xml into doc/docbook/en/index.xml (so that the text makes sense)
  • merge doc/docbook/fr/user.xml and doc/docbook/fr/installation.xml into doc/docbook/fr/index.xml (so that the text makes sense)
  • move doc/docbook/en/installation/* and doc/docbook/en/user/* to doc/docbook/en/
  • move doc/docbook/fr/installation/* and doc/docbook/fr/user/* to doc/docbook/fr/
  • update the Makefile.am accordingly

#8
Updated by Alexandre Quessy 12 months ago

Should be done before Scenic 1.0's released. (planned June 18th, 2012)

#9
Updated by Alexandre Quessy 12 months ago

  • % Done changed from 100 to 0

#10
Updated by Alexandre Quessy 12 months ago

  • Priority changed from Low to High

#11
Updated by Alexandre Quessy 12 months ago

  • Estimated time set to 20.00

Merged both english manuals. We need to reorder the pages in the user-manual.xml.in file, and then we do the same with the French version.

(git mv, git rm, edit Makefile.am and configure.ac and user-manual.xml.in)

#12
Updated by Alexandre Quessy 11 months ago

Andrew, did you cleanup the english manual? When do you plan to merge the French version of the manual? We want to make some release quite soon. :) I will have do it if you can't do it before 1-2 weeks from now.

#13
Updated by Alexandre Quessy 10 months ago

  • Assignee changed from Andrew Kozloski to Alexandre Quessy

Done for both French and English.

#14
Updated by Alexandre Quessy 10 months ago

  • Status changed from New to Closed

Also available in: Atom PDF