Debian Documentation Project (DDP) TODO List
Urgent TO-DO list:
- Ruthless stale documentation reaping.
- Stipulate and document a documentation hierarchy. Basically, complete the Documentation Policy document, with the assent and blessing of the Debian Web team. This involves consistency of file location in the web area and in packages. There is a draft available here but needs to be revised yet.
- Add a way to manage translations automatically just as the website's WML sources are.
- Determine which information should be included in the CD and automate a method to create the proper index. Relevant information is here and subversion holds some scripts that need to be polished and added to a cron job.
Ideas:
The following is just a list of ideas that came up in several threads
on our mailing list. Thus, these may be good and bad ideas. :-)
-
Provide a consistent interface to all of Debian's manpages, like many others are doing already like Ubuntu, FreeBSD, NetBSD, OpenBSD, HP (HPUX), IBM (AIX), SGI (Irix), and Sun (Solaris). Curiously enough there are several servers (like Fifi) are already providing all of Debian's manpages. This is Bug #264589.
There is a first beta version available at manpages.debian.org
- Implement URN's. This would enable users to check for documentation locally, on the web site, or on mirrors. Local configuration could be used to indicate closer or more convenient mirrors or ordering. doc-base could use URNs to point to documents rather than using file names.
- I thought about what output formats we want to include in the debian
packages (.deb's). We need to include HTML (that's the policy) but
some people may also want to have PostScript or TEXT versions. So I
had the idea of distributing the SGML source _only_ and creating the
formats the user wants to have at runtime (could be installation time
as well as afterwards). This has several advantages:
- the .debs would be small
- greatest flexibility
- we could even adjust links when compiling the docs, i.e. replacing Internet links to local ones if the files are present !!!
- it's probably easier to keep an overall index page up-to-date (a la dwww)
- people need to have debiandoc-sgml installed (but that's not big)
- formatting will take a few seconds (not too much but simply unpackaging would be faster)
doc-base could define the fundamentals of this type of system, since it tracks metadata for documents.
- Determine which documents are actually being used (or sought) by our users so we can focus on them. That's something that has not been yet investigated. Some sources of information might be the user's mailing list (conduct a poll), the web log statistics (of both the main www site and mirrors) and, since documents are also distributed as Debian packages, the popularity-contest data.
- Generate the information of available manuals presented in the website by extracting the info (which is provided by manual.defs and version.defs) automatically from VCS.
- Make it possible to track translation status based on information from the VCS site. Consider re-using the framework developed by the debian-installer for the installation manual.
- Track document 'last-changed' status so that the users browsing the documents available can determine whether the document applies (or doesn't apply) to them.
- Consider providing documentation for users in non-english languages (VCS holds directories for some languages and some documentation originally written in a language which is not English)
- Consider providing an interactive mechanism for users to annotate documents through a wiki-like interface, separated from the main presentation on the website or using the same presentation. This feedback could be used by document author's and, even if open to abuse, it has worked quite well for other documentation projects (PHP)
- Have users use a generic bug tracking system for documentation. It is used for those documents that provide a package but not all documents do so.
